Struct calf_vec::generic::CalfVec

pub struct CalfVec<'a, M: Meta, T, const N: usize> { /* fields omitted */ }

Contiguous growable array type that is either borrowed, stack allocated or heap allocated.

This type behaves just like a Vec<T> but with a few more optimizations. Just like Cow, the data can be simply borrowed as long as it is not accessed mutably. Otherwise just like SmallVec the data is stored on the stack as long as the buffer's capacity does not exceed a given capacity (given as type parameter N). If this capacity is exceeded, then the data is stored on the heap.

The maximum capacity of a CalfVec<T> array depends on the metadata format used which is given as type parameter M, implementing the Meta trait. By default the wide::Meta is used, which behaves just like Vec. In this case, the maximum capacity is std::usize::MAX.

Examples

let slice = &[1, 2, 3];
let mut calf: CalfVec<'_, u8, 32> = CalfVec::borrowed(slice); // at this point, data is only borrowed.
calf[0]; // => 1
calf[0] = 4; // because it is modified, the data is copied here.
assert_eq!(calf, [4, 2, 3])

A CalfVec can also be directly created to own its data:

let owned: CalfVec<'_, u8, 32> = CalfVec::owned(vec![1, 2, 3]);

Implementations

impl<'a, M: Meta, T, const N: usize> CalfVec<'a, M, T, N>

pub fn borrowed<B: AsRef<[T]> + ?Sized>(borrowed: &'a B) -> CalfVec<'a, M, T, N>

Create a new CalfVec from borrowed data.

The input's data is not copied until it is accessed mutably.

Example

let slice = &[1, 2, 3];
let mut calf: CalfVec<'_, u8, 32> = CalfVec::borrowed(slice); // at this point, data is only borrowed.
calf[0]; // => 1
calf[0] = 4; // because it is modified, the data is copied here.
assert_eq!(calf, [4, 2, 3])

pub fn owned<O: Into<Vec<T>>>(owned: O) -> CalfVec<'a, M, T, N>

Create a new CalfVec from owned data.

The input is consumed and stored either on the stack if it does not exceed the capacity parameter N, or on the heap otherwise.

pub fn try_into_slice(self) -> Result<&'a [T], Self>

Try to convert this CalfVec into a borrowed slice.

Returns Ok(slice) if the data is borrowed, and Err(self) otherwise.

This is a cost-free operation.

pub fn try_into_vec(self) -> Result<Vec<T>, Self>

Try to convert this CalfVec into Vec.

Returns Ok(vec) if the data is owned and on the heap, and Err(self) otherwise.

This is a cost-free operation.

pub fn into_vec(self) -> Vec<T> where
    T: Clone, 

Convert this CalfVec into Vec.

If the data is borrowed it will be cloned. If the data is owned on the stack, it will be moved on the heap. If the data is owned on the heap, then this is a cost-free operation.

pub fn as_ptr(&self) -> *const T

Returns a raw pointer to the vector's buffer.

The caller must ensure that the vector outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the vector may cause its buffer to be reallocated, which would also make any pointers to it invalid.

The caller must also ensure that the memory the pointer (non-transitively) points to is never written to (except inside an UnsafeCell) using this pointer or any pointer derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.

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

Extracts a slice containing the entire vector.

Equivalent to &s[..].

pub fn is_owned(&self) -> bool

Returns true if the data is owned, i.e. if to_mut would be a no-op.

pub fn is_borrowed(&self) -> bool

Returns true if the data is borrowed, i.e. if to_mut would require additional work.

pub fn len(&self) -> usize

Returns the length of the array.

pub fn capacity(&self) -> Option<usize>

Returns the capacity of the owned buffer, or None if the data is only borrowed.

impl<'a, M: Meta, T, const N: usize> CalfVec<'a, M, T, N> where
    T: Clone, 

pub fn own(&mut self) -> usize

pub fn as_mut_ptr(&mut self) -> *mut T

Returns an unsafe mutable pointer to the vector's buffer.

The caller must ensure that the vector outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the vector may cause its buffer to be reallocated, which would also make any pointers to it invalid.

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

Extracts a mutable slice of the entire vector.

Equivalent to &mut s[..].

pub fn truncate(&mut self, len: usize)

Shortens the vector, keeping the first len elements and dropping the rest.

If len is greater than the vector's current length, this has no effect.

The [drain] method can emulate truncate, but causes the excess elements to be returned instead of dropped.

Note that this method has no effect on the allocated capacity of the vector.

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

Reserves capacity for at least additional more elements to be inserted in the given CalfVec<T>. The collection may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

Panics

Panics if the new capacity exceeds M::MAX_LENGTH bytes.

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

Reserves the minimum capacity for exactly additional more elements to be inserted in the given Vec<T>. After calling reserve_exact, capacity will be greater than or equal to self.len() + additional. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore, capacity can not be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

Panics

Panics if the new capacity overflows usize.

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of the vector with a lower bound.

The capacity will remain at least as large as N, the length and the supplied value.

If the resulting capacity is equal to N, the data will be placed on the stack if it is not already.

This function has no effect if the data is borrowed.

Panics

Panics if the current capacity is smaller than the supplied minimum capacity.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the vector as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements.

pub fn insert(&mut self, index: usize, element: T)

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

Panics

Panics if index > len.

pub fn remove(&mut self, index: usize) -> T

Removes and returns the element at position index within the vector, shifting all elements after it to the left.

Panics

Panics if index is out of bounds.

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

Moves all the elements of other into Self, leaving other empty.

Panics

Panics if the number of elements in the vector overflows.

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

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

Iterates over the slice other, clones each element, and then appends it to this CalfVec. The other vector is traversed in-order.

Note that this function is same as 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).

pub fn clear(&mut self)

Clears the vector, removing all values.

Note that this method has no effect on the allocated capacity of the vector.

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

Appends an element to the back of a collection.

Panics

Panics if the new capacity exceeds M::MAX_LENGTH bytes.

pub fn pop(&mut self) -> Option<T>

Removes the last element from a vector and returns it, or None if it is empty.

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

Removes all but the first of consecutive elements in the vector satisfying a given equality relation.

The same_bucket function is passed references to two elements from the vector and must determine if the elements compare equal. The elements are passed in opposite order from their order in the slice, so if same_bucket(a, b) returns true, a is removed.

If the vector is sorted, this removes all duplicates.

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

Removes all but the first of consecutive elements in the vector that resolve to the same key.

If the vector is sorted, this removes all duplicates.

pub fn dedup(&mut self) where
    T: PartialEq, 

Removes consecutive repeated elements in the vector according to the PartialEq trait implementation.

If the vector is sorted, this removes all duplicates.

Trait Implementations

impl<'a, M: Meta, T, const N: usize> AsMut<[T]> for CalfVec<'a, M, T, N> where
    T: Clone, 

fn as_mut(&mut self) -> &mut [T]

Performs the conversion.

impl<'a, M: Meta, T, const N: usize> AsMut<CalfVec<'a, M, T, N>> for CalfVec<'a, M, T, N>

fn as_mut(&mut self) -> &mut CalfVec<'a, M, T, N>

Performs the conversion.

impl<'a, M: Meta, T, const N: usize> AsRef<[T]> for CalfVec<'a, M, T, N>

fn as_ref(&self) -> &[T]

Performs the conversion.

impl<'a, M: Meta, T, const N: usize> AsRef<CalfVec<'a, M, T, N>> for CalfVec<'a, M, T, N>

fn as_ref(&self) -> &CalfVec<'a, M, T, N>

Performs the conversion.

impl<'a, M: Meta, T: Debug, const N: usize> Debug for CalfVec<'a, M, T, N>

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

Formats the value using the given formatter.

impl<'a, M: Meta, T, const N: usize> Deref for CalfVec<'a, M, T, N>

type Target = [T]

The resulting type after dereferencing.

fn deref(&self) -> &[T]

Dereferences the value.

impl<'a, M: Meta, T, const N: usize> DerefMut for CalfVec<'a, M, T, N> where
    T: Clone, 

fn deref_mut(&mut self) -> &mut [T]

Mutably dereferences the value.

impl<'a, M: Meta, T, const N: usize> Drop for CalfVec<'a, M, T, N>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, M: Meta, T, const N: usize> Extend<T> for CalfVec<'a, M, T, N> where
    T: Clone, 

fn extend<I: IntoIterator<Item = T>>(&mut self, iterator: 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<'a, M: Meta, T, const N: usize> From<&'a [T]> for CalfVec<'a, M, T, N>

fn from(s: &'a [T]) -> CalfVec<'a, M, T, N>

Performs the conversion.

impl<'a, M: Meta, T, const N: usize> From<Vec<T>> for CalfVec<'a, M, T, N>

fn from(v: Vec<T>) -> CalfVec<'a, M, T, N>

Performs the conversion.

impl<'v, 'a, M: Meta, T, const N: usize> IntoIterator for &'v CalfVec<'a, M, T, N>

type Item = &'v T

The type of the elements being iterated over.

type IntoIter = Iter<'v, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'v, 'a, M: Meta, T, const N: usize> IntoIterator for &'v mut CalfVec<'a, M, T, N> where
    T: Clone, 

type Item = &'v mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'v, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, M: Meta, T, const N: usize> IntoIterator for CalfVec<'a, M, T, N> where
    T: Clone, 

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<M, T, N>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, A, B, M: Meta, const N: usize, const O: usize, '_> PartialEq<&'_ [B; O]> for CalfVec<'a, M, A, N> where
    A: PartialEq<B>, 

fn eq(&self, other: &&[B; O]) -> bool

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

fn ne(&self, other: &&[B; O]) -> bool

This method tests for !=.

impl<'a, A, B, M: Meta, const N: usize, '_> PartialEq<&'_ [B]> for CalfVec<'a, M, A, N> where
    A: PartialEq<B>, 

fn eq(&self, other: &&[B]) -> bool

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

fn ne(&self, other: &&[B]) -> bool

This method tests for !=.

impl<'a, A, B, M: Meta, const N: usize, '_> PartialEq<&'_ mut [B]> for CalfVec<'a, M, A, N> where
    A: PartialEq<B>, 

fn eq(&self, other: &&mut [B]) -> bool

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

fn ne(&self, other: &&mut [B]) -> bool

This method tests for !=.

impl<'a, A, B, M: Meta, const N: usize, const O: usize> PartialEq<[B; O]> for CalfVec<'a, M, A, N> where
    A: PartialEq<B>, 

fn eq(&self, other: &[B; O]) -> bool

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

fn ne(&self, other: &[B; O]) -> bool

This method tests for !=.

impl<'b, A, B, M: Meta, const N: usize> PartialEq<CalfVec<'b, M, B, N>> for Vec<A> where
    A: PartialEq<B>, 

fn eq(&self, other: &CalfVec<'b, M, B, N>) -> bool

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

fn ne(&self, other: &CalfVec<'b, M, B, N>) -> bool

This method tests for !=.

impl<'b, A, B, M: Meta, const N: usize, '_> PartialEq<CalfVec<'b, M, B, N>> for &'_ [A] where
    A: PartialEq<B>, 

fn eq(&self, other: &CalfVec<'b, M, B, N>) -> bool

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

fn ne(&self, other: &CalfVec<'b, M, B, N>) -> bool

This method tests for !=.

impl<'b, A, B, M: Meta, const N: usize, '_> PartialEq<CalfVec<'b, M, B, N>> for &'_ mut [A] where
    A: PartialEq<B>, 

fn eq(&self, other: &CalfVec<'b, M, B, N>) -> bool

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

fn ne(&self, other: &CalfVec<'b, M, B, N>) -> bool

This method tests for !=.

impl<'b, A, B, M: Meta, const N: usize, '_> PartialEq<CalfVec<'b, M, B, N>> for Cow<'_, [A]> where
    A: PartialEq<B>,
    A: Clone, 

fn eq(&self, other: &CalfVec<'b, M, B, N>) -> bool

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

fn ne(&self, other: &CalfVec<'b, M, B, N>) -> bool

This method tests for !=.

impl<'b, A, B, M: Meta, const N: usize, const O: usize> PartialEq<CalfVec<'b, M, B, N>> for [A; O] where
    A: PartialEq<B>, 

fn eq(&self, other: &CalfVec<'b, M, B, N>) -> bool

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

fn ne(&self, other: &CalfVec<'b, M, B, N>) -> bool

This method tests for !=.

impl<'b, A, B, M: Meta, const N: usize, const O: usize, '_> PartialEq<CalfVec<'b, M, B, N>> for &'_ [A; O] where
    A: PartialEq<B>, 

fn eq(&self, other: &CalfVec<'b, M, B, N>) -> bool

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

fn ne(&self, other: &CalfVec<'b, M, B, N>) -> bool

This method tests for !=.

impl<'a, 'b, A, B, O: Meta, P: Meta, const N: usize, const M: usize> PartialEq<CalfVec<'b, P, B, M>> for CalfVec<'a, O, A, N> where
    A: PartialEq<B>, 

fn eq(&self, other: &CalfVec<'b, P, B, M>) -> bool

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

fn ne(&self, other: &CalfVec<'b, P, B, M>) -> bool

This method tests for !=.

impl<'a, A, B, M: Meta, const N: usize, '_> PartialEq<Cow<'_, [B]>> for CalfVec<'a, M, A, N> where
    A: PartialEq<B>,
    B: Clone, 

fn eq(&self, other: &Cow<'_, [B]>) -> bool

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

fn ne(&self, other: &Cow<'_, [B]>) -> bool

This method tests for !=.

impl<'a, A, B, M: Meta, const N: usize> PartialEq<Vec<B>> for CalfVec<'a, M, A, N> where
    A: PartialEq<B>, 

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

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

fn ne(&self, other: &Vec<B>) -> bool

This method tests for !=.

impl<'a, M: Meta + Send, T: Sync, const N: usize> Send for CalfVec<'a, M, T, N>

impl<'a, M: Meta + Sync, T: Sync, const N: usize> Sync for CalfVec<'a, M, T, N>