Enum tinyvec::TinyVec

pub enum TinyVec<A: Array> {
    Inline(ArrayVec<A>),
    Heap(Vec<A::Item>),
}

This is supported on crate feature alloc only.

A vector that starts inline, but can automatically move to the heap.

• Requires the alloc feature

A TinyVec is either an Inline(ArrayVec) or Heap(Vec). The interface for the type as a whole is a bunch of methods that just match on the enum variant and then call the same method on the inner vec.

Construction

Because it's an enum, you can construct a TinyVec simply by making an ArrayVec or Vec and then putting it into the enum.

There is also a macro

let empty_tv = tiny_vec!([u8; 16]);
let some_ints = tiny_vec!([i32; 4] => 1, 2, 3);

Variants

Inline(ArrayVec<A>)

This is supported on crate feature alloc only.

Heap(Vec<A::Item>)

This is supported on crate feature alloc only.

Implementations

impl<A: Array> TinyVec<A>

#[must_use]pub fn is_heap(&self) -> bool

Returns whether elements are on heap

#[must_use]pub fn is_inline(&self) -> bool

Returns whether elements are on stack

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the vector as much as possible.
It is inlined if length is less than A::CAPACITY.

use tinyvec::*;
let mut tv = tiny_vec!([i32; 2] => 1, 2, 3);
assert!(tv.is_heap());
let _ = tv.pop();
assert!(tv.is_heap());
tv.shrink_to_fit();
assert!(tv.is_inline());

pub fn move_to_the_heap(&mut self)

Moves the content of the TinyVec to the heap, if it's inline.

use tinyvec::*;
let mut tv = tiny_vec!([i32; 4] => 1, 2, 3);
assert!(tv.is_inline());
tv.move_to_the_heap();
assert!(tv.is_heap());

pub fn move_to_the_heap_and_reserve(&mut self, n: usize)

If TinyVec is inline, moves the content of it to the heap. Also reserves additional space.

use tinyvec::*;
let mut tv = tiny_vec!([i32; 4] => 1, 2, 3);
assert!(tv.is_inline());
tv.move_to_the_heap_and_reserve(32);
assert!(tv.is_heap());
assert!(tv.capacity() >= 35);

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

Reserves additional space. Moves to the heap if array can't hold n more items

use tinyvec::*;
let mut tv = tiny_vec!([i32; 4] => 1, 2, 3, 4);
assert!(tv.is_inline());
tv.reserve(1);
assert!(tv.is_heap());
assert!(tv.capacity() >= 5);

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

Reserves additional space. Moves to the heap if array can't hold n more items

From Vec::reserve_exact

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.

use tinyvec::*;
let mut tv = tiny_vec!([i32; 4] => 1, 2, 3, 4);
assert!(tv.is_inline());
tv.reserve_exact(1);
assert!(tv.is_heap());
assert!(tv.capacity() >= 5);

#[must_use]pub fn with_capacity(cap: usize) -> Self

Makes a new TinyVec with at least the given capacity.

If the requested capacity is less than or equal to the array capacity you get an inline vec. If it's greater than you get a heap vec.

let t = TinyVec::<[u8; 10]>::with_capacity(5);
assert!(t.is_inline());
assert!(t.capacity() >= 5);

let t = TinyVec::<[u8; 10]>::with_capacity(20);
assert!(t.is_heap());
assert!(t.capacity() >= 20);

impl<A: Array> TinyVec<A>

pub fn append(&mut self, other: &mut Self)

Move all values from other into this vec.

pub fn swap_remove(&mut self, index: usize) -> A::Item

Remove an element, swapping the end of the vec into its place.

Panics

• If the index is out of bounds.

Example

use tinyvec::*;
let mut tv = tiny_vec!([&str; 4] => "foo", "bar", "quack", "zap");

assert_eq!(tv.swap_remove(1), "bar");
assert_eq!(tv.as_slice(), &["foo", "zap", "quack"][..]);

assert_eq!(tv.swap_remove(0), "foo");
assert_eq!(tv.as_slice(), &["quack", "zap"][..]);

pub fn pop(&mut self) -> Option<A::Item>

Remove and return the last element of the vec, if there is one.

Failure

• If the vec is empty you get None.

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

Removes the item at index, shifting all others down by one index.

Returns the removed element.

Panics

If the index is out of bounds.

Example

use tinyvec::*;
let mut tv = tiny_vec!([i32; 4] => 1, 2, 3);
assert_eq!(tv.remove(1), 2);
assert_eq!(tv.as_slice(), &[1, 3][..]);

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

The length of the vec (in elements).

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

The capacity of the TinyVec.

When not heap allocated this is fixed based on the array type. Otherwise its the result of the underlying Vec::capacity.

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

Reduces the vec's length to the given value.

If the vec is already shorter than the input, nothing happens.

#[must_use]pub fn as_mut_ptr(&mut self) -> *mut A::Item

A mutable pointer to the backing array.

Safety

This pointer has provenance over the entire backing array/buffer.

#[must_use]pub fn as_ptr(&self) -> *const A::Item

A const pointer to the backing array.

Safety

This pointer has provenance over the entire backing array/buffer.

pub fn retain<F: FnMut(&A::Item) -> bool>(&mut self, acceptable: F)

Walk the vec and keep only the elements that pass the predicate given.

Example

use tinyvec::*;

let mut tv = tiny_vec!([i32; 10] => 1, 2, 3, 4);
tv.retain(|&x| x % 2 == 0);
assert_eq!(tv.as_slice(), &[2, 4][..]);

#[must_use]pub fn as_mut_slice(&mut self) -> &mut [A::Item]

Helper for getting the mut slice.

#[must_use]pub fn as_slice(&self) -> &[A::Item]

Helper for getting the shared slice.

pub fn clear(&mut self)

Removes all elements from the vec.

pub fn drain<R: RangeBounds<usize>>(&mut self, range: R) -> TinyVecDrain<'_, A>

Creates a draining iterator that removes the specified range in the vector and yields the removed items.

Note: This method has significant performance issues compared to matching on the TinyVec and then calling drain on the Inline or Heap value inside. The draining iterator has to branch on every single access. It is provided for simplicity and compatability only.

Panics

• If the start is greater than the end
• If the end is past the edge of the vec.

Example

use tinyvec::*;
let mut tv = tiny_vec!([i32; 4] => 1, 2, 3);
let tv2: TinyVec<[i32; 4]> = tv.drain(1..).collect();
assert_eq!(tv.as_slice(), &[1][..]);
assert_eq!(tv2.as_slice(), &[2, 3][..]);

tv.drain(..);
assert_eq!(tv.as_slice(), &[]);

pub fn extend_from_slice(&mut self, sli: &[A::Item]) where
    A::Item: Clone, 

Clone each element of the slice into this vec.

use tinyvec::*;
let mut tv = tiny_vec!([i32; 4] => 1, 2);
tv.extend_from_slice(&[3, 4]);
assert_eq!(tv.as_slice(), [1, 2, 3, 4]);

#[must_use]pub fn from_array_len(data: A, len: usize) -> Self

Wraps up an array and uses the given length as the initial length.

Note that the From impl for arrays assumes the full length is used.

Panics

The length must be less than or equal to the capacity of the array.

pub fn insert(&mut self, index: usize, item: A::Item)

Inserts an item at the position given, moving all following elements +1 index.

Panics

• If index > len

Example

use tinyvec::*;
let mut tv = tiny_vec!([i32; 10] => 1, 2, 3);
tv.insert(1, 4);
assert_eq!(tv.as_slice(), &[1, 4, 2, 3]);
tv.insert(4, 5);
assert_eq!(tv.as_slice(), &[1, 4, 2, 3, 5]);

#[must_use]pub fn is_empty(&self) -> bool

If the vec is empty.

#[must_use]pub fn new() -> Self

Makes a new, empty vec.

pub fn push(&mut self, val: A::Item)

Place an element onto the end of the vec.

Panics

• If the length of the vec would overflow the capacity.

use tinyvec::*;
let mut tv = tiny_vec!([i32; 10] => 1, 2, 3);
tv.push(4);
assert_eq!(tv.as_slice(), &[1, 2, 3, 4]);

pub fn resize(&mut self, new_len: usize, new_val: A::Item) where
    A::Item: Clone, 

Resize the vec to the new length.

If it needs to be longer, it's filled with clones of the provided value. If it needs to be shorter, it's truncated.

Example

use tinyvec::*;

let mut tv = tiny_vec!([&str; 10] => "hello");
tv.resize(3, "world");
assert_eq!(tv.as_slice(), &["hello", "world", "world"][..]);

let mut tv = tiny_vec!([i32; 10] => 1, 2, 3, 4);
tv.resize(2, 0);
assert_eq!(tv.as_slice(), &[1, 2][..]);

pub fn resize_with<F: FnMut() -> A::Item>(&mut self, new_len: usize, f: F)

Resize the vec to the new length.

If it needs to be longer, it's filled with repeated calls to the provided function. If it needs to be shorter, it's truncated.

Example

use tinyvec::*;

let mut tv = tiny_vec!([i32; 3] => 1, 2, 3);
tv.resize_with(5, Default::default);
assert_eq!(tv.as_slice(), &[1, 2, 3, 0, 0][..]);

let mut tv = tiny_vec!([i32; 2]);
let mut p = 1;
tv.resize_with(4, || {
  p *= 2;
  p
});
assert_eq!(tv.as_slice(), &[2, 4, 8, 16][..]);

pub fn split_off(&mut self, at: usize) -> Self

Splits the collection at the point given.

• [0, at) stays in this vec
• [at, len) ends up in the new vec.

Panics

• if at > len

Example

use tinyvec::*;
let mut tv = tiny_vec!([i32; 4] => 1, 2, 3);
let tv2 = tv.split_off(1);
assert_eq!(tv.as_slice(), &[1][..]);
assert_eq!(tv2.as_slice(), &[2, 3][..]);

pub fn splice<R, I>(
    &mut self,
    range: R,
    replacement: I
) -> TinyVecSplice<'_, A, Fuse<I::IntoIter>> where
    R: RangeBounds<usize>,
    I: IntoIterator<Item = A::Item>, 

Creates a splicing iterator that removes the specified range in the vector, yields the removed items, and replaces them with elements from the provided iterator.

splice fuses the provided iterator, so elements after the first None are ignored.

Panics

• If the start is greater than the end.
• If the end is past the edge of the vec.
• If the provided iterator panics.

Example

use tinyvec::*;
let mut tv = tiny_vec!([i32; 4] => 1, 2, 3);
let tv2: TinyVec<[i32; 4]> = tv.splice(1.., 4..=6).collect();
assert_eq!(tv.as_slice(), &[1, 4, 5, 6][..]);
assert_eq!(tv2.as_slice(), &[2, 3][..]);

tv.splice(.., None);
assert_eq!(tv.as_slice(), &[]);

pub fn try_from_array_len(data: A, len: usize) -> Result<Self, A>

Wraps an array, using the given length as the starting length.

If you want to use the whole length of the array, you can just use the From impl.

Failure

If the given length is greater than the capacity of the array this will error, and you'll get the array back in the Err.

Trait Implementations

impl<A: Array> AsMut<[<A as Array>::Item]> for TinyVec<A>

#[must_use]fn as_mut(&mut self) -> &mut [A::Item]

Performs the conversion.

impl<A: Array> AsRef<[<A as Array>::Item]> for TinyVec<A>

#[must_use]fn as_ref(&self) -> &[A::Item]

Performs the conversion.

impl<A: Array> Binary for TinyVec<A> where
    A::Item: Binary, 

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

Formats the value using the given formatter.

impl<A: Array> Borrow<[<A as Array>::Item]> for TinyVec<A>

#[must_use]fn borrow(&self) -> &[A::Item]

Immutably borrows from an owned value.

impl<A: Array> BorrowMut<[<A as Array>::Item]> for TinyVec<A>

#[must_use]fn borrow_mut(&mut self) -> &mut [A::Item]

Mutably borrows from an owned value.

impl<A: Clone + Array> Clone for TinyVec<A> where
    A::Item: Clone, 

fn clone(&self) -> TinyVec<A>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A: Array> Debug for TinyVec<A> where
    A::Item: Debug, 

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

Formats the value using the given formatter.

impl<A: Array> Default for TinyVec<A>

#[must_use]fn default() -> Self

Returns the "default value" for a type.

impl<A: Array> Deref for TinyVec<A>

type Target = [A::Item]

The resulting type after dereferencing.

#[must_use]fn deref(&self) -> &Self::Target

Dereferences the value.

impl<A: Array> DerefMut for TinyVec<A>

#[must_use]fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de, A: Array> Deserialize<'de> for TinyVec<A> where
    A::Item: Deserialize<'de>, 

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<A: Array> Display for TinyVec<A> where
    A::Item: Display, 

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

Formats the value using the given formatter.

impl<A: Array> Eq for TinyVec<A> where
    A::Item: Eq, 

impl<A: Array> Extend<<A as Array>::Item> for TinyVec<A>

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

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, A, '_> From<&'_ [T]> for TinyVec<A> where
    T: Clone + Default,
    A: Array<Item = T>, 

#[must_use]fn from(slice: &[T]) -> Self

Performs the conversion.

impl<T, A, '_> From<&'_ mut [T]> for TinyVec<A> where
    T: Clone + Default,
    A: Array<Item = T>, 

#[must_use]fn from(slice: &mut [T]) -> Self

Performs the conversion.

impl<A: Array> From<A> for TinyVec<A>

fn from(array: A) -> Self

Performs the conversion.

impl<A: Array> From<ArrayVec<A>> for TinyVec<A>

#[must_use]fn from(arr: ArrayVec<A>) -> Self

Performs the conversion.

impl<A: Array> FromIterator<<A as Array>::Item> for TinyVec<A>

#[must_use]fn from_iter<T: IntoIterator<Item = A::Item>>(iter: T) -> Self

Creates a value from an iterator.

impl<A: Array> Hash for TinyVec<A> where
    A::Item: Hash, 

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<A: Array, I: SliceIndex<[A::Item]>> Index<I> for TinyVec<A>

type Output = <I as SliceIndex<[A::Item]>>::Output

The returned type after indexing.

#[must_use]fn index(&self, index: I) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<A: Array, I: SliceIndex<[A::Item]>> IndexMut<I> for TinyVec<A>

#[must_use]fn index_mut(&mut self, index: I) -> &mut Self::Output

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

impl<A: Array> IntoIterator for TinyVec<A>

type Item = A::Item

The type of the elements being iterated over.

type IntoIter = TinyVecIterator<A>

Which kind of iterator are we turning this into?

#[must_use]fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, A: Array> IntoIterator for &'a mut TinyVec<A>

type Item = &'a mut A::Item

The type of the elements being iterated over.

type IntoIter = IterMut<'a, A::Item>

Which kind of iterator are we turning this into?

#[must_use]fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, A: Array> IntoIterator for &'a TinyVec<A>

type Item = &'a A::Item

The type of the elements being iterated over.

type IntoIter = Iter<'a, A::Item>

Which kind of iterator are we turning this into?

#[must_use]fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<A: Array> LowerExp for TinyVec<A> where
    A::Item: LowerExp, 

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

Formats the value using the given formatter.

impl<A: Array> LowerHex for TinyVec<A> where
    A::Item: LowerHex, 

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

Formats the value using the given formatter.

impl<A: Array> Octal for TinyVec<A> where
    A::Item: Octal, 

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

Formats the value using the given formatter.

impl<A: Array> Ord for TinyVec<A> where
    A::Item: Ord, 

#[must_use]fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

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

Restrict a value to a certain interval.

impl<A: Array, '_> PartialEq<&'_ [<A as Array>::Item]> for TinyVec<A> where
    A::Item: PartialEq, 

#[must_use]fn eq(&self, other: &&[A::Item]) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A: Array, '_> PartialEq<&'_ A> for TinyVec<A> where
    A::Item: PartialEq, 

#[must_use]fn eq(&self, other: &&A) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A: Array> PartialEq<TinyVec<A>> for TinyVec<A> where
    A::Item: PartialEq, 

#[must_use]fn eq(&self, other: &Self) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A: Array> PartialOrd<TinyVec<A>> for TinyVec<A> where
    A::Item: PartialOrd, 

#[must_use]fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A: Array> Pointer for TinyVec<A> where
    A::Item: Pointer, 

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

Formats the value using the given formatter.

impl<A: Array> Serialize for TinyVec<A> where
    A::Item: Serialize, 

#[must_use]fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<A: Array> UpperExp for TinyVec<A> where
    A::Item: UpperExp, 

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

Formats the value using the given formatter.

impl<A: Array> UpperHex for TinyVec<A> where
    A::Item: UpperHex, 

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

Formats the value using the given formatter.