[][src]Struct vec1::Vec1

pub struct Vec1<T>(_);

std::vec::Vec wrapper which guarantees to have at least 1 element.

Vec1<T> dereferences to &[T] and &mut [T] as functionality exposed through this can not change the length.

Methods of Vec which can be called without reducing the length (e.g. capacity(), reserve()) are exposed through wrappers with the same function signature.

Methods of Vec which could reduce the length to 0 are implemented with a try_ prefix returning a Result. (e.g. try_pop(&self), try_truncate(), etc.).

Methods with returned Option<T> with None if the length was 0 (and do not reduce the length) now return T. (e.g. first, last, first_mut, etc.).

All stable traits and methods implemented on Vec<T> should also be implemented on Vec1<T> (except if they make no sense to implement due to the len 1 guarantee). Note that some small things are still missing e.g. Vec1 does not implement drain currently as drains generic argument is R: RangeArgument<usize> and RangeArgument is not stable.

Implementations

impl<T> Vec1<T>[src]

pub fn new(first: T) -> Self[src]

Creates a new Vec1 instance containing a single element.

This is roughly Vec1(vec![first]).

pub fn from_vec(vec: Vec<T>) -> StdResult<Self, Vec<T>>[src]

👎 Deprecated since 1.2.0:

does not work with ? use Vec1::try_from_vec() instead

Tries to create a Vec1<T> from a Vec<T>.

The fact that the input is returned as error if it's empty, means that it doesn't work well with the ? operator. It naming is also semantic sub-optimal as it's not a "from" but "try from" conversion. Which is why this method is now deprecated. Instead use try_from_vec and once TryFrom is stable it will be possible to use try_from, too.

Errors

If the input is empty the input is returned as error.

pub fn try_from_vec(vec: Vec<T>) -> StdResult<Self, Size0Error>[src]

Tries to create a Vec1<T> from a normal Vec<T>.

Errors

This will fail if the input Vec<T> is empty. The returned error is a Size0Error instance, as such this means the input vector will be dropped if it's empty. But this is normally fine as it only happens if the Vec<T> is empty.

Examples

let vec1 = Vec1::try_from_vec(vec![1u8, 2, 3])
    .unwrap();
assert_eq!(vec1, vec![1u8, 2, 3]);

If you need to return a Option<Vec1<T>> you can use .ok() on the returned result:

fn foobar(input: Vec<u8>) -> Option<Vec1<u8>> {
    let mut res = Vec1::try_from_vec(input).ok()?;
    for x in res.iter_mut() {
        *x *= 2;
    }
    Some(res)
}

pub fn with_capacity(first: T, capacity: usize) -> Self[src]

Creates a new Vec1 with a given capacity and a given "first" element.

pub fn into_vec(self) -> Vec<T>[src]

Turns this Vec1 into a Vec.

pub fn mapped<F, N>(self, map_fn: F) -> Vec1<N> where
    F: FnMut(T) -> N, 
[src]

Create a new Vec1 by consuming self and mapping each element.

This is useful as it keeps the knowledge that the length is >= 1, even through the old Vec1 is consumed and turned into an iterator.

Example

let data = vec1![1u8,2,3];

let data = data.mapped(|x|x*2);
assert_eq!(data, vec![2,4,6]);

// without mapped
let data = Vec1::try_from_vec(data.into_iter().map(|x|x*2).collect::<Vec<_>>()).unwrap();
assert_eq!(data, vec![4,8,12]);

pub fn mapped_ref<F, N>(&self, map_fn: F) -> Vec1<N> where
    F: FnMut(&T) -> N, 
[src]

Create a new Vec1 by mapping references to the elements of self.

The benefit to this compared to Iterator::map is that it's known that the length will still be at least 1 when creating the new Vec1.

pub fn mapped_mut<F, N>(&mut self, map_fn: F) -> Vec1<N> where
    F: FnMut(&mut T) -> N, 
[src]

Create a new Vec1 by mapping mutable references to the elements of self.

The benefit to this compared to Iterator::map is that it's known that the length will still be at least 1 when creating the new Vec1.

pub fn try_mapped<F, N, E>(self, map_fn: F) -> Result<Vec1<N>, E> where
    F: FnMut(T) -> Result<N, E>, 
[src]

Create a new Vec1 by consuming self and mapping each element to a Result.

This is useful as it keeps the knowledge that the length is >= 1, even through the old Vec1 is consumed and turned into an iterator.

As this method consumes self, returning an error means that this vec is dropped. I.e. this method behaves roughly like using a chain of into_iter(), map, collect::<Result<Vec<N>,E>> and then converting the Vec back to a Vec1.

Errors

Once any call to map_fn returns a error that error is directly returned by this method.

Example

let data = vec1![1,2,3];

let data: Result<Vec1<u8>, &'static str> = data.try_mapped(|x| Err("failed"));
assert_eq!(data, Err("failed"));

pub fn try_mapped_ref<F, N, E>(&self, map_fn: F) -> Result<Vec1<N>, E> where
    F: FnMut(&T) -> Result<N, E>, 
[src]

Create a new Vec1 by mapping references to the elements of self to Results.

The benefit to this compared to Iterator::map is that it's known that the length will still be at least 1 when creating the new Vec1.

Errors

Once any call to map_fn returns a error that error is directly returned by this method.

pub fn try_mapped_mut<F, N, E>(&mut self, map_fn: F) -> Result<Vec1<N>, E> where
    F: FnMut(&mut T) -> Result<N, E>, 
[src]

Create a new Vec1 by mapping mutable references to the elements of self to Results.

The benefit to this compared to Iterator::map is that it's known that the length will still be at least 1 when creating the new Vec1.

Errors

Once any call to map_fn returns a error that error is directly returned by this method.

pub fn last(&self) -> &T[src]

Returns a reference to the last element.

As Vec1 always contains at least one element there is always a last element.

pub fn last_mut(&mut self) -> &mut T[src]

Returns a mutable reference to the last element.

As Vec1 always contains at least one element there is always a last element.

pub fn first(&self) -> &T[src]

Returns a reference to the first element.

As Vec1 always contains at least one element there is always a first element.

pub fn first_mut(&mut self) -> &mut T[src]

Returns a mutable reference to the first element.

As Vec1 always contains at least one element there is always a first element.

pub fn try_truncate(&mut self, len: usize) -> StdResult<(), Size0Error>[src]

Truncates the vec1 to given length.

Errors

If len is 0 an error is returned as the length >= 1 constraint must be uphold.

pub fn try_swap_remove(&mut self, index: usize) -> StdResult<T, Size0Error>[src]

Calls swap_remove on the inner vec if length >= 2.

Errors

If len is 1 an error is returned as the length >= 1 constraint must be uphold.

pub fn try_remove(&mut self, index: usize) -> StdResult<T, Size0Error>[src]

Calls remove on the inner vec if length >= 2.

Errors

If len is 1 an error is returned as the length >= 1 constraint must be uphold.

pub fn try_split_off(&mut self, at: usize) -> StdResult<Vec1<T>, Size0Error>[src]

Calls split_off on the inner vec if both resulting parts have length >= 1.

Errors

If after the split any part would be empty an error is returned as the length >= 1 constraint must be uphold.

pub fn dedup_by_key<F, K>(&mut self, key: F) where
    F: FnMut(&mut T) -> K,
    K: PartialEq<K>, 
[src]

Calls dedup_by_key on the inner vec.

While this can remove elements it will never produce a empty vector from an non empty vector.

pub fn dedup_by<F>(&mut self, same_bucket: F) where
    F: FnMut(&mut T, &mut T) -> bool
[src]

Calls dedup_by_key on the inner vec.

While this can remove elements it will never produce a empty vector from an non empty vector.

pub fn try_pop(&mut self) -> StdResult<T, Size0Error>[src]

Tries to remove the last element from the Vec1.

Returns an error if the length is currently 1 (so the try_pop would reduce the length to 0).

Errors

If len is 1 an error is returned as the length >= 1 constraint must be uphold.

pub fn as_vec(&self) -> &Vec<T>[src]

Return a reference to the underlying Vec.

pub fn splice<R, I>(
    &mut self,
    range: R,
    replace_with: I
) -> StdResult<Splice<<I as IntoIterator>::IntoIter>, Size0Error> where
    I: IntoIterator<Item = T>,
    R: RangeBounds<usize>, 
[src]

Calls splice on the underlying vec if it will not produce an empty vec.

Errors

If range covers the whole vec and the replacement iterator doesn't yield any value an error is returned.

This means that if an error is returned next might still have been called once on the replace_with iterator.

pub fn split_off_first(self) -> (T, Vec<T>)[src]

Splits off the first element of this vector and returns it together with the rest of the vector.

Examples

assert_eq!((0, vec![]), vec1![0].split_off_first());
assert_eq!((0, vec![1, 2, 3]), vec1![0, 1, 2, 3].split_off_first());

pub fn split_off_last(self) -> (Vec<T>, T)[src]

Splits off the last element of this vector and returns it together with the rest of the vector.

Examples

assert_eq!((vec![], 0), vec1![0].split_off_last());
assert_eq!((vec![0, 1, 2], 3), vec1![0, 1, 2, 3].split_off_last());

impl Vec1<u8>[src]

pub fn to_ascii_uppercase(&self) -> Vec1<u8>[src]

Works like &[u8].to_ascii_uppercase() but returns a Vec1<T> instead of a Vec<T>

pub fn to_ascii_lowercase(&self) -> Vec1<u8>[src]

Works like &[u8].to_ascii_lowercase() but returns a Vec1<T> instead of a Vec<T>

impl<T> Vec1<T>[src]

pub fn reserve(&mut self, additional: usize)[src]

pub fn reserve_exact(&mut self, additional: usize)[src]

pub fn shrink_to_fit(&mut self)[src]

pub fn as_mut_slice(&mut self) -> &mut [T][src]

pub fn push(&mut self, value: T)[src]

pub fn append(&mut self, other: &mut Vec<T>)[src]

pub fn insert(&mut self, idx: usize, val: T)[src]

pub fn len(&self) -> usize[src]

pub fn capacity(&self) -> usize[src]

pub fn as_slice(&self) -> &[T][src]

impl<T> Vec1<T> where
    T: Clone
[src]

pub fn try_resize(
    &mut self,
    new_len: usize,
    value: T
) -> StdResult<(), Size0Error>
[src]

Calls resize on the underlying Vec if new_len >= 1.

Errors

If the new_len is 0 an error is returned as the length >= 1 constraint must be uphold.

pub fn extend_from_slice(&mut self, other: &[T])[src]

impl<T> Vec1<T> where
    T: PartialEq<T>, 
[src]

pub fn dedub(&mut self)[src]

impl<T> Vec1<T> where
    T: PartialEq<T>, 
[src]

pub fn dedup(&mut self)[src]

Trait Implementations

impl<T> AsMut<[T]> for Vec1<T>[src]

impl<T> AsMut<Vec1<T>> for Vec1<T>[src]

impl<T> AsRef<[T]> for Vec1<T>[src]

impl<T> AsRef<Vec<T>> for Vec1<T>[src]

impl<T> AsRef<Vec1<T>> for Vec1<T>[src]

impl<T> Borrow<[T]> for Vec1<T>[src]

impl<T> Borrow<Vec<T>> for Vec1<T>[src]

impl<T> BorrowMut<[T]> for Vec1<T>[src]

impl<T: Clone> Clone for Vec1<T>[src]

impl<T: Debug> Debug for Vec1<T>[src]

impl<T> Default for Vec1<T> where
    T: Default
[src]

impl<T> Deref for Vec1<T>[src]

type Target = [T]

The resulting type after dereferencing.

impl<T> DerefMut for Vec1<T>[src]

impl<T: Eq> Eq for Vec1<T>[src]

impl<'a, T> Extend<&'a T> for Vec1<T> where
    T: 'a + Copy
[src]

impl<T> Extend<T> for Vec1<T>[src]

impl<T: Hash> Hash for Vec1<T>[src]

impl<T, O, R> Index<R> for Vec1<T> where
    Vec<T>: Index<R, Output = O>,
    O: ?Sized
[src]

type Output = O

The returned type after indexing.

impl<T, O, R> IndexMut<R> for Vec1<T> where
    Vec<T>: IndexMut<R, Output = O>,
    O: ?Sized
[src]

impl<T> Into<Arc<[T]>> for Vec1<T>[src]

impl<T> Into<Box<[T]>> for Vec1<T>[src]

impl<T> Into<Rc<[T]>> for Vec1<T>[src]

impl<T> Into<Vec<T>> for Vec1<T>[src]

impl<T> Into<VecDeque<T>> for Vec1<T>[src]

impl<T> IntoIterator for Vec1<T>[src]

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

impl<'a, T> IntoIterator for &'a Vec1<T>[src]

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

impl<'a, T> IntoIterator for &'a mut Vec1<T>[src]

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

impl<T: Ord> Ord for Vec1<T>[src]

impl<A, B> PartialEq<B> for Vec1<A> where
    Vec<A>: PartialEq<B>, 
[src]

impl<A, B> PartialEq<Vec1<B>> for Vec1<A> where
    A: PartialEq<B>, 
[src]

impl<T: PartialOrd> PartialOrd<Vec1<T>> for Vec1<T>[src]

impl<T> StructuralEq for Vec1<T>[src]

impl<'a, T> TryFrom<&'a [T]> for Vec1<T> where
    T: Clone
[src]

type Error = Size0Error

The type returned in the event of a conversion error.

impl<'a, T> TryFrom<&'a mut [T]> for Vec1<T> where
    T: Clone
[src]

type Error = Size0Error

The type returned in the event of a conversion error.

impl<'a> TryFrom<&'a str> for Vec1<u8>[src]

type Error = Size0Error

The type returned in the event of a conversion error.

impl<T> TryFrom<BinaryHeap<T>> for Vec1<T>[src]

type Error = Size0Error

The type returned in the event of a conversion error.

impl<T> TryFrom<Box<[T]>> for Vec1<T>[src]

type Error = Size0Error

The type returned in the event of a conversion error.

impl TryFrom<CString> for Vec1<u8>[src]

Warning: This impl is unstable and requires nightly, it's not covert by semver stability guarantees.

type Error = Size0Error

The type returned in the event of a conversion error.

fn try_from(string: CString) -> StdResult<Self, Self::Error>[src]

Like Vec's From<CString> this will treat the '\0' as not part of the string.

impl TryFrom<String> for Vec1<u8>[src]

type Error = Size0Error

The type returned in the event of a conversion error.

impl<T> TryFrom<Vec<T>> for Vec1<T>[src]

type Error = Size0Error

The type returned in the event of a conversion error.

impl<T> TryFrom<VecDeque<T>> for Vec1<T>[src]

type Error = Size0Error

The type returned in the event of a conversion error.

Auto Trait Implementations

impl<T> RefUnwindSafe for Vec1<T> where
    T: RefUnwindSafe

impl<T> Send for Vec1<T> where
    T: Send

impl<T> Sync for Vec1<T> where
    T: Sync

impl<T> Unpin for Vec1<T> where
    T: Unpin

impl<T> UnwindSafe for Vec1<T> where
    T: UnwindSafe

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<I> IntoIterator for I where
    I: Iterator
[src]

type Item = <I as Iterator>::Item

The type of the elements being iterated over.

type IntoIter = I

Which kind of iterator are we turning this into?

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

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

The type returned in the event of a conversion error.