[][src]Crate tinyvec

For all those times when you need just a little bit of vec support.

What This Is

This crate provides 100% safe code alternatives to both arrayvec and smallvec.

Being 100% safe means that you have to have some sort of compromise compared to the versions using unsafe. In this case, the compromise is that the element type must implement Default to be usable in these vecs. However, that still allows you to use quite a few types, so I think that you'll find these vecs useful in many cases.

  • ArrayVec is an array-backed vec-like structure with a fixed capacity. If you try to grow the length past the array's capacity it will error or panic (depending on the method used).
  • SliceVec is similar, but instead of the vec having an owned array, it holds onto a unique borrow of a slice. This means that it's far cheaper to pass around (since you don't move the whole array), but it can be trickier to thread a lifetime marker everywhere through all your function signatures.
  • (alloc feature) TinyVec is an enum that's either an "Inline" ArrayVec or a "Heap" Vec. If it's Inline and you try to grow the ArrayVec beyond its array capacity it will quietly transition into Heap mode and then continue the operation.

Crate Goals

  1. The crate is 100% safe code. Not just a safe API, there are also no unsafe internals. #![forbid(unsafe_code)].
  2. No required dependencies.
    • We might provide optional dependencies for extra functionality (eg: serde compatibility).
  3. The intended API is that, as much as possible, these types are essentially a "drop-in" replacement for the standard Vec type. Because of the "no unsafe" rule this can't be done perfectly.
    • Stable Vec methods that the vecs here also have should be the same general signature.
    • Unstable Vec methods are sometimes provided via a crate feature, but if so they also require a Nightly compiler.
    • Some methods are provided that are not part of the Vec type, such as additional constructor methods. In this case, the names are rather long and whimsical in the hopes that they don't clash with any possible future methods of Vec.
    • If, in the future, Vec stabilizes a method that clashes with an existing extra method here then we'll simply be forced to release a 2.y.z version. Not the end of the world.
    • Some methods of Vec are simply inappropriate and will not be implemented here. For example, this crate cannot possibly implement from_raw_parts because it cannot call unsafe methods.

Macros

array_vec

Helper to make an ArrayVec.

tiny_vec

Helper to make a TinyVec.

Structs

ArraySet

An array-backed set

ArrayVec

An array-backed, vector-like data structure.

ArrayVecDrain

Draining iterator for ArrayVec

ArrayVecIterator

Iterator for consuming an ArrayVec and returning owned elements.

InsertError

Error resulting from attempting to insert into a full array

Iter

Type returned by ArraySet::iter

SliceVec

A slice-backed vector-like data structure.

SliceVecDrain

Draining iterator for SliceVec

TinyVecDrain

Draining iterator for TinyVecDrain

Enums

TinyVec

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

TinyVecIterator

Iterator for consuming an TinyVec and returning owned elements.

Traits

Array

A trait for types that are an array.