Struct SmallVec

struct SmallVec<A: Array> { ... }

A Vec-like container that can store a small number of elements inline.

SmallVec acts like a vector, but can store a limited amount of data inline within the SmallVec struct rather than in a separate allocation. If the data exceeds this limit, the SmallVec will "spill" its data onto the heap, allocating a new buffer to hold it.

The amount of data that a SmallVec can store inline depends on its backing store. The backing store can be any type that implements the Array trait; usually it is a small fixed-sized array. For example a SmallVec<[u64; 8]> can hold up to eight 64-bit integers inline.

Example

use smallvec::SmallVec;
let mut v = SmallVec::<[u8; 4]>::new(); // initialize an empty vector

// The vector can hold up to 4 items without spilling onto the heap.
v.extend(0..4);
assert_eq!(v.len(), 4);
assert!(!v.spilled());

// Pushing another element will force the buffer to spill:
v.push(4);
assert_eq!(v.len(), 5);
assert!(v.spilled());

Implementations

impl<A: Array> SmallVec<A>

fn resize(self: &mut Self, len: usize, value: <A as >::Item)

Resizes the vector so that its length is equal to len.

If len is less than the current length, the vector simply truncated.

If len is greater than the current length, value is appended to the vector until its length equals len.

fn from_elem(elem: <A as >::Item, n: usize) -> Self

Creates a SmallVec with n copies of elem.

use smallvec::SmallVec;

let v = SmallVec::<[char; 128]>::from_elem('d', 2);
assert_eq!(v, SmallVec::from_buf(['d', 'd']));

impl<A: Array> SmallVec<A>

fn from_slice(slice: &[<A as >::Item]) -> Self

Copy the elements from a slice into a new SmallVec.

For slices of Copy types, this is more efficient than SmallVec::from(slice).

fn insert_from_slice(self: &mut Self, index: usize, slice: &[<A as >::Item])

Copy elements from a slice into the vector at position index, shifting any following elements toward the back.

For slices of Copy types, this is more efficient than insert.

fn extend_from_slice(self: &mut Self, slice: &[<A as >::Item])

Copy elements from a slice and append them to the vector.

For slices of Copy types, this is more efficient than extend.

impl<A: Array> SmallVec<A>

fn new() -> SmallVec<A>

Construct an empty vector

fn with_capacity(n: usize) -> Self

Construct an empty vector with enough capacity pre-allocated to store at least n elements.

Will create a heap allocation only if n is larger than the inline capacity.

# use smallvec::SmallVec;

let v: SmallVec<[u8; 3]> = SmallVec::with_capacity(100);

assert!(v.is_empty());
assert!(v.capacity() >= 100);

fn from_vec(vec: Vec<<A as >::Item>) -> SmallVec<A>

Construct a new SmallVec from a Vec<A::Item>.

Elements will be copied to the inline buffer if vec.capacity() <= Self::inline_capacity().

use smallvec::SmallVec;

let vec = vec![1, 2, 3, 4, 5];
let small_vec: SmallVec<[_; 3]> = SmallVec::from_vec(vec);

assert_eq!(&*small_vec, &[1, 2, 3, 4, 5]);

fn from_buf(buf: A) -> SmallVec<A>

Constructs a new SmallVec on the stack from an A without copying elements.

use smallvec::SmallVec;

let buf = [1, 2, 3, 4, 5];
let small_vec: SmallVec<_> = SmallVec::from_buf(buf);

assert_eq!(&*small_vec, &[1, 2, 3, 4, 5]);

fn from_buf_and_len(buf: A, len: usize) -> SmallVec<A>

Constructs a new SmallVec on the stack from an A without copying elements. Also sets the length, which must be less or equal to the size of buf.

use smallvec::SmallVec;

let buf = [1, 2, 3, 4, 5, 0, 0, 0];
let small_vec: SmallVec<_> = SmallVec::from_buf_and_len(buf, 5);

assert_eq!(&*small_vec, &[1, 2, 3, 4, 5]);

unsafe fn from_buf_and_len_unchecked(buf: MaybeUninit<A>, len: usize) -> SmallVec<A>

Constructs a new SmallVec on the stack from an A without copying elements. Also sets the length. The user is responsible for ensuring that len <= A::size().

use smallvec::SmallVec;
use std::mem::MaybeUninit;

let buf = [1, 2, 3, 4, 5, 0, 0, 0];
let small_vec: SmallVec<_> = unsafe {
    SmallVec::from_buf_and_len_unchecked(MaybeUninit::new(buf), 5)
};

assert_eq!(&*small_vec, &[1, 2, 3, 4, 5]);

unsafe fn set_len(self: &mut Self, new_len: usize)

Sets the length of a vector.

This will explicitly set the size of the vector, without actually modifying its buffers, so it is up to the caller to ensure that the vector is actually the specified size.

fn inline_size(self: &Self) -> usize

The maximum number of elements this vector can hold inline

fn len(self: &Self) -> usize

The number of elements stored in the vector

fn is_empty(self: &Self) -> bool

Returns true if the vector is empty

fn capacity(self: &Self) -> usize

The number of items the vector can hold without reallocating

fn spilled(self: &Self) -> bool

Returns true if the data has spilled into a separate heap-allocated buffer.

fn drain<R>(self: &mut Self, range: R) -> Drain<'_, A>
where
    R: RangeBounds<usize>

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

Note 1: The element range is removed even if the iterator is only partially consumed or not consumed at all.

Note 2: It is unspecified how many elements are removed from the vector if the Drain value is 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.

fn push(self: &mut Self, value: <A as >::Item)

Append an item to the vector.

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

Remove an item from the end of the vector and return it, or None if empty.

fn append<B>(self: &mut Self, other: &mut SmallVec<B>)
where
    B: Array<Item = <A as >::Item>

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

Example

# use smallvec::{SmallVec, smallvec};
let mut v0: SmallVec<[u8; 16]> = smallvec![1, 2, 3];
let mut v1: SmallVec<[u8; 32]> = smallvec![4, 5, 6];
v0.append(&mut v1);
assert_eq!(*v0, [1, 2, 3, 4, 5, 6]);
assert_eq!(*v1, []);

fn grow(self: &mut Self, new_cap: usize)

Re-allocate to set the capacity to max(new_cap, inline_size()).

Panics if new_cap is less than the vector's length or if the capacity computation overflows usize.

fn try_grow(self: &mut Self, new_cap: usize) -> Result<(), CollectionAllocErr>

Re-allocate to set the capacity to max(new_cap, inline_size()).

Panics if new_cap is less than the vector's length

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

Reserve capacity for additional more elements to be inserted.

May reserve more space to avoid frequent reallocations.

Panics if the capacity computation overflows usize.

fn try_reserve(self: &mut Self, additional: usize) -> Result<(), CollectionAllocErr>

Reserve capacity for additional more elements to be inserted.

May reserve more space to avoid frequent reallocations.

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

Reserve the minimum capacity for additional more elements to be inserted.

Panics if the new capacity overflows usize.

fn try_reserve_exact(self: &mut Self, additional: usize) -> Result<(), CollectionAllocErr>

Reserve the minimum capacity for additional more elements to be inserted.

fn shrink_to_fit(self: &mut Self)

Shrink the capacity of the vector as much as possible.

When possible, this will move data from an external heap buffer to the vector's inline storage.

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

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

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

This does not re-allocate. If you want the vector's capacity to shrink, call shrink_to_fit after truncating.

fn as_slice(self: &Self) -> &[<A as >::Item]

Extracts a slice containing the entire vector.

Equivalent to &s[..].

fn as_mut_slice(self: &mut Self) -> &mut [<A as >::Item]

Extracts a mutable slice of the entire vector.

Equivalent to &mut s[..].

fn swap_remove(self: &mut Self, index: usize) -> <A as >::Item

Remove the element at position index, replacing it with the last element.

This does not preserve ordering, but is O(1).

Panics if index is out of bounds.

fn clear(self: &mut Self)

Remove all elements from the vector.

fn remove(self: &mut Self, index: usize) -> <A as >::Item

Remove and return the element at position index, shifting all elements after it to the left.

Panics if index is out of bounds.

fn insert(self: &mut Self, index: usize, element: <A as >::Item)

Insert an element at position index, shifting all elements after it to the right.

Panics if index > len.

fn insert_many<I: IntoIterator<Item = <A as >::Item>>(self: &mut Self, index: usize, iterable: I)

Insert multiple elements at position index, shifting all following elements toward the back.

fn into_vec(self: Self) -> Vec<<A as >::Item>

Convert a SmallVec to a Vec, without reallocating if the SmallVec has already spilled onto the heap.

fn into_boxed_slice(self: Self) -> Box<[<A as >::Item]>

Converts a SmallVec into a Box<[T]> without reallocating if the SmallVec has already spilled onto the heap.

Note that this will drop any excess capacity.

fn into_inner(self: Self) -> Result<A, Self>

Convert the SmallVec into an A if possible. Otherwise return Err(Self).

This method returns Err(Self) if the SmallVec is too short (and the A contains uninitialized elements), or if the SmallVec is too long (and all the elements were spilled to the heap).

fn retain<F: FnMut(&mut <A as >::Item) -> bool>(self: &mut Self, f: F)

Retains only the elements specified by the predicate.

In other words, remove all elements e such that f(&e) returns false. This method operates in place and preserves the order of the retained elements.

fn retain_mut<F: FnMut(&mut <A as >::Item) -> bool>(self: &mut Self, f: F)

Retains only the elements specified by the predicate.

This method is identical in behaviour to retain; it is included only to maintain api-compatibility with std::Vec, where the methods are separate for historical reasons.

fn dedup(self: &mut Self)
where
    <A as >::Item: PartialEq<<A as >::Item>

Removes consecutive duplicate elements.

fn dedup_by<F>(self: &mut Self, same_bucket: F)
where
    F: FnMut(&mut <A as >::Item, &mut <A as >::Item) -> bool

Removes consecutive duplicate elements using the given equality relation.

fn dedup_by_key<F, K>(self: &mut Self, key: F)
where
    F: FnMut(&mut <A as >::Item) -> K,
    K: PartialEq<K>

Removes consecutive elements that map to the same key.

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

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

If new_len is greater than len, the SmallVec 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 SmallVec in the order they have been generated.

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

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

Added for std::vec::Vec compatibility (added in Rust 1.33.0)

# use smallvec::{smallvec, SmallVec};
let mut vec : SmallVec<[_; 4]> = smallvec![1, 2, 3];
vec.resize_with(5, Default::default);
assert_eq!(&*vec, &[1, 2, 3, 0, 0]);

let mut vec : SmallVec<[_; 4]> = smallvec![];
let mut p = 1;
vec.resize_with(4, || { p *= 2; p });
assert_eq!(&*vec, &[2, 4, 8, 16]);

unsafe fn from_raw_parts(ptr: *mut <A as >::Item, length: usize, capacity: usize) -> SmallVec<A>

Creates a SmallVec directly from the raw components of another SmallVec.

Safety

This is highly unsafe, due to the number of invariants that aren't checked:

  • ptr needs to have been previously allocated via SmallVec for its spilled storage (at least, it's highly likely to be incorrect if it wasn't).
  • ptr's A::Item type needs to be the same size and alignment that it was allocated with
  • length needs to be less than or equal to capacity.
  • capacity needs to be the capacity that the pointer was allocated with.

Violating these may cause problems like corrupting the allocator's internal data structures.

Additionally, capacity must be greater than the amount of inline storage A has; that is, the new SmallVec must need to spill over into heap allocated storage. This condition is asserted against.

The ownership of ptr is effectively transferred to the SmallVec which may then deallocate, reallocate or change the contents of memory pointed to by the pointer at will. Ensure that nothing else uses the pointer after calling this function.

Examples

# use smallvec::{smallvec, SmallVec};
use std::mem;
use std::ptr;

fn main() {
    let mut v: SmallVec<[_; 1]> = smallvec![1, 2, 3];

    // Pull out the important parts of `v`.
    let p = v.as_mut_ptr();
    let len = v.len();
    let cap = v.capacity();
    let spilled = v.spilled();

    unsafe {
        // Forget all about `v`. The heap allocation that stored the
        // three values won't be deallocated.
        mem::forget(v);

        // Overwrite memory with [4, 5, 6].
        //
        // This is only safe if `spilled` is true! Otherwise, we are
        // writing into the old `SmallVec`'s inline storage on the
        // stack.
        assert!(spilled);
        for i in 0..len {
            ptr::write(p.add(i), 4 + i);
        }

        // Put everything back together into a SmallVec with a different
        // amount of inline storage, but which is still less than `cap`.
        let rebuilt = SmallVec::<[_; 2]>::from_raw_parts(p, len, cap);
        assert_eq!(&*rebuilt, &[4, 5, 6]);
    }
}

fn as_ptr(self: &Self) -> *const <A as >::Item

Returns a raw pointer to the vector's buffer.

fn as_mut_ptr(self: &mut Self) -> *mut <A as >::Item

Returns a raw mutable pointer to the vector's buffer.

impl<T, N: usize> SmallVec<[T; N]>

const fn new_const() -> Self

Construct an empty vector.

This is a const version of SmallVec::new that is enabled by the feature const_new, with the limitation that it only works for arrays.

const fn from_const(items: [T; N]) -> Self

The array passed as an argument is moved to be an inline version of SmallVec.

This is a const version of SmallVec::from_buf that is enabled by the feature const_new, with the limitation that it only works for arrays.

unsafe const fn from_const_with_len_unchecked(items: [T; N], len: usize) -> Self

Constructs a new SmallVec on the stack from an array without copying elements. Also sets the length. The user is responsible for ensuring that len <= N.

This is a const version of SmallVec::from_buf_and_len_unchecked that is enabled by the feature const_new, with the limitation that it only works for arrays.

impl<'a, A: Array> From for SmallVec<A>

fn from(slice: &'a [<A as >::Item]) -> SmallVec<A>

impl<A> Freeze for SmallVec<A>

impl<A> RefUnwindSafe for SmallVec<A>

impl<A> Sync for SmallVec<A>

impl<A> Unpin for SmallVec<A>

impl<A> UnsafeUnpin for SmallVec<A>

impl<A> UnwindSafe for SmallVec<A>

impl<A: Array> AsMut for SmallVec<A>

fn as_mut(self: &mut Self) -> &mut [<A as >::Item]

impl<A: Array> AsRef for SmallVec<A>

fn as_ref(self: &Self) -> &[<A as >::Item]

impl<A: Array> Borrow for SmallVec<A>

fn borrow(self: &Self) -> &[<A as >::Item]

impl<A: Array> BorrowMut for SmallVec<A>

fn borrow_mut(self: &mut Self) -> &mut [<A as >::Item]

impl<A: Array> Clone for SmallVec<A>

fn clone(self: &Self) -> SmallVec<A>
fn clone_from(self: &mut Self, source: &Self)

impl<A: Array> Debug for SmallVec<A>

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

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

fn default() -> SmallVec<A>

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

fn deref(self: &Self) -> &[<A as >::Item]

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

fn deref_mut(self: &mut Self) -> &mut [<A as >::Item]

impl<A: Array> Drop for SmallVec<A>

fn drop(self: &mut Self)

impl<A: Array> Eq for SmallVec<A>

impl<A: Array> Extend for SmallVec<A>

fn extend<I: IntoIterator<Item = <A as >::Item>>(self: &mut Self, iterable: I)

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

fn from(array: A) -> SmallVec<A>

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

fn from(vec: Vec<<A as >::Item>) -> SmallVec<A>

impl<A: Array> FromIterator for SmallVec<A>

fn from_iter<I: IntoIterator<Item = <A as >::Item>>(iterable: I) -> SmallVec<A>

impl<A: Array> Hash for SmallVec<A>

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

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

fn into_iter(self: Self) -> <Self as >::IntoIter

impl<A: Array> Ord for SmallVec<A>

fn cmp(self: &Self, other: &SmallVec<A>) -> Ordering

impl<A: Array> PartialOrd for SmallVec<A>

fn partial_cmp(self: &Self, other: &SmallVec<A>) -> Option<Ordering>

impl<A: Array> Send for SmallVec<A>

impl<A: Array, B: Array> PartialEq for SmallVec<A>

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

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

fn index(self: &Self, index: I) -> &<I as >::Output

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

fn index_mut(self: &mut Self, index: I) -> &mut <I as >::Output

impl<P, T> Receiver for SmallVec<A>

impl<T> Any for SmallVec<A>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for SmallVec<A>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for SmallVec<A>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for SmallVec<A>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for SmallVec<A>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for SmallVec<A>

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for SmallVec<A>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for SmallVec<A>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for SmallVec<A>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>