Struct unempty::Vec

pub struct Vec<T> { /* private fields */ }

A non-empty vector of items.

The first entry is statically stored. Additional items are dynamically stored with std::vec::Vec<T>; for memory and performance characteristics please review the documentation for that module and type.

Completeness

std::vec::Vec has many methods. These are being implemented as needed! Please submit a PR or create an issue if you need a method!

Unstable/nightly features

Does not currently support customizable allocators, nightly features, or unstable features. If any of these are desired, please submit a PR for the parts you need!

Implementations

impl<T> Vec<T>

pub fn new(first: T) -> Self

Efficiently constructs a new instance with a single item.

The underlying std::vec::Vec does not allocate unless more items are pushed.

Examples

let vec: unempty::Vec<usize> = unempty::Vec::new(1);

pub fn with_capacity(first: T, capacity: Capacity<1>) -> Self

Constructs a new instance with a single item and the specified capacity.

Capacity is in two parts: the guaranteed portion of this data structure consumes 1 “capacity”, and the dynamic portion of this data structure consumes the rest (the “additional capacity”).

“Additional capacity” follows the same rules as std::vec::Vec:

The vector will be able to hold at least additional capacity elements without reallocating. This method is allowed to allocate for more elements than capacity. If additional capacity is 0, the vector will not allocate.

It is important to note that although the returned vector has the minimum additional capacity specified, the vector will have a length of 1. For an explanation of the difference between length and capacity, see std::vec::Vec::with_capacity.

If it is imporant to know the exact allocated capacity, always use the capacity method after construction.

When T is a zero-sized type, there will be no allocation and the additional capacity will always be usize::MAX.

Panics

Panics if the additional capacity exceeds isize::MAX bytes.

Examples

let v = unempty::Vec::with_capacity("abc", Capacity::new_total(10));

pub fn capacity(&self) -> Capacity<1>

Returns the number of elements the Vec can hold without reallocating.

Examples

let cap = Capacity::new_total(10);
let v = unempty::Vec::with_capacity("abc", cap);
assert_eq!(v.capacity(), cap);

pub fn len(&self) -> usize

Returns the number of elements in the data structure, also referred to as its ‘length’. Includes both static and dynamic portions of the data structure.

Examples

let a = unempty::vec![1, 2, 3];
assert_eq!(a.len(), 3);

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements. This method always returns false, because by defition an unempty::Vec cannot be empty. This method is included for API completeness and to make Clippy happy.

Examples

let mut v = unempty::Vec::new("abcd");
assert!(!v.is_empty());

pub fn pop(self) -> (Option<Self>, T)

Removes the last element from a vector and returns it.

If you’d like to pop the first element, consider using VecDeque::pop_front instead.

Consuming self

Since this method may pop when there is only one item in the vector, it consumes the vector and optionally returns the vector with its new size.

This is necessary because if the vector is popped when there is only one item, the “non-empty” guarantee of unempty::Vec is no longer possible.

If this API is not desired, convert the instance to a std::vec::Vec and use that; std::vec::Vec has no such guarantee.

Examples

let vec = unempty::vec![1, 2];

let (vec, last) = vec.pop();
assert_eq!(last, 2);
assert_eq!(vec, Some(unempty::vec![1]));

let (vec, last) = vec.expect("already tested").pop();
assert_eq!(last, 1);
assert_eq!(vec, None);

pub fn push(&mut self, item: T)

Appends an element to the back of the vector.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

Examples

let mut vec = unempty::vec![1, 2];
vec.push(3);
assert_eq!(vec, unempty::vec![1, 2, 3]);

Trait Implementations

impl<T: Clone> Clone for Vec<T>

fn clone(&self) -> Vec<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Vec<T>

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

Formats the value using the given formatter.

impl<T> Extend<T> for Vec<T>

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T> From<Vec<T>> for Vec<T>

fn from(sv: Vec<T>) -> Self

Converts to this type from the input type.

impl<T> From<Vec<T>> for VecDeque<T>

fn from(sv: Vec<T>) -> Self

Converts to this type from the input type.

impl<T> Index<usize> for Vec<T>

type Output = T

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> IndexMut<usize> for Vec<T>

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T: PartialEq> PartialEq<Vec<T>> for Vec<T>

fn eq(&self, other: &Vec<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> TryFrom<Vec<T, Global>> for Vec<T>

type Error = TryFromError

The type returned in the event of a conversion error.

fn try_from(sv: Vec<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> TryFrom<VecDeque<T, Global>> for Vec<T>

type Error = TryFromError

The type returned in the event of a conversion error.

fn try_from(sv: VecDeque<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<T: Eq> Eq for Vec<T>

impl<T> StructuralEq for Vec<T>

impl<T> StructuralPartialEq for Vec<T>