Crate minivec[−][src]
Expand description
A space-optimized version of alloc::vec::Vec
that’s only the size of a single pointer!
Ideal for low-level APIs where ABI calling conventions will typically require most structs be
spilled onto the stack and copied instead of being passed solely in registers.
For example, in the x64 msvc ABI:
There’s a strict one-to-one correspondence between a function call’s arguments and the registers used for those arguments. Any argument that doesn’t fit in 8 bytes, or isn’t 1, 2, 4, or 8 bytes, must be passed by reference. A single argument is never spread across multiple registers.
In addition, its single word size makes it ideal for use as a struct member where multiple
inclusions of Vec
as a field can balloon the size.
MiniVec
is a #[repr(transparent)]
struct so its layout is that of core::ptr::NonNull<u8>
.
In general, MiniVec
aims to be API compatible with what’s currently stable in the stdlib so some
Nightly features are not supported. MiniVec
also supports myriad extensions, one such being
support for over-alignment via the associated function with_alignment
.
MiniVec
has stable implementations of the following nightly-only associated functions on Vec
:
MiniVec
has the following associated functions not found in Vec
:
MiniVec
has the following extensions to the existing Vec
API:
push
returns a mutable reference to the newly created element
Eventual TODO’s:
- add
try_reserve
methods once stable - add myriad specializations to associated functions such as
FromIterator
once stable - add Allocator support once stable
Macros
mini_vec!
is a macro similar in spirit to the stdlib’s vec!
.
Structs
Drain
is an iterator that removes the selected sub-range from the MiniVec
and returns the removed elements to
the caller lazily.
DrainFilter
is a version of Drain
that uses the supplied predicate to determine when an element should be
removed from the MiniVec
and returned to the user.
IntoIter
is an iterator type that consumes the MiniVec
and transfers ownership of the contained elements to the
caller when iterated.
MiniVec
is a space-optimized implementation of alloc::vec::Vec
that is only the size of a single pointer and
also extends portions of its API, including support for over-aligned allocations. MiniVec
also aims to bring as
many Nightly features from Vec
to stable toolchains as is possible. In many cases, it is a drop-in replacement
for the “real” Vec
.
Splice
is an iterator that removes a sub-section of the backing MiniVec
and then replaces it with the contents
of another iterator. The removed sub-section and the iterator used to replace it can have independent lengths.
Enums
LayoutErr
is the error type returned by the alignment-based associated functions for MiniVec