| 1 | #![cfg_attr (not(feature = "std" ), no_std)]
|
| 2 | #![forbid (unsafe_code)]
|
|---|
| 3 | #![cfg_attr (
|
|---|
| 4 | feature = "nightly_slice_partition_dedup" ,
|
|---|
| 5 | feature(slice_partition_dedup)
|
|---|
| 6 | )]
|
|---|
| 7 | #![cfg_attr (docs_rs, feature(doc_cfg))]
|
|---|
| 8 | #![warn (clippy::missing_inline_in_public_items)]
|
|---|
| 9 | #![warn (clippy::must_use_candidate)]
|
|---|
| 10 | #![warn (missing_docs)]
|
|---|
| 11 |
|
|---|
| 12 | //! `tinyvec` provides 100% safe vec-like data structures.
|
|---|
| 13 | //!
|
|---|
| 14 | //! ## Provided Types
|
|---|
| 15 | //! With no features enabled, this crate provides the [`ArrayVec`] type, which
|
|---|
| 16 | //! is an array-backed storage. You can push values into the array and pop them
|
|---|
| 17 | //! out of the array and so on. If the array is made to overflow it will panic.
|
|---|
| 18 | //!
|
|---|
| 19 | //! Similarly, there is also a [`SliceVec`] type available, which is a vec-like
|
|---|
| 20 | //! that's backed by a slice you provide. You can add and remove elements, but
|
|---|
| 21 | //! if you overflow the slice it will panic.
|
|---|
| 22 | //!
|
|---|
| 23 | //! With the `alloc` feature enabled, the crate also has a [`TinyVec`] type.
|
|---|
| 24 | //! This is an enum type which is either an `Inline(ArrayVec)` or a `Heap(Vec)`.
|
|---|
| 25 | //! If a `TinyVec` is `Inline` and would overflow it automatically transitions
|
|---|
| 26 | //! itself into being `Heap` mode instead of a panic.
|
|---|
| 27 | //!
|
|---|
| 28 | //! All of this is done with no `unsafe` code within the crate. Technically the
|
|---|
| 29 | //! `Vec` type from the standard library uses `unsafe` internally, but *this
|
|---|
| 30 | //! crate* introduces no new `unsafe` code into your project.
|
|---|
| 31 | //!
|
|---|
| 32 | //! The limitation is that the element type of a vec from this crate must
|
|---|
| 33 | //! support the [`Default`] trait. This means that this crate isn't suitable for
|
|---|
| 34 | //! all situations, but a very surprising number of types do support `Default`.
|
|---|
| 35 | //!
|
|---|
| 36 | //! ## Other Features
|
|---|
| 37 | //! * `grab_spare_slice` lets you get access to the "inactive" portions of an
|
|---|
| 38 | //! ArrayVec.
|
|---|
| 39 | //! * `rustc_1_40` makes the crate assume a minimum rust version of `1.40.0`,
|
|---|
| 40 | //! which allows some better internal optimizations.
|
|---|
| 41 | //! * `serde` provides a `Serialize` and `Deserialize` implementation for
|
|---|
| 42 | //! [`TinyVec`] and [`ArrayVec`] types, provided the inner item also has an
|
|---|
| 43 | //! implementation.
|
|---|
| 44 | //!
|
|---|
| 45 | //! ## API
|
|---|
| 46 | //! The general goal of the crate is that, as much as possible, the vecs here
|
|---|
| 47 | //! should be a "drop in" replacement for the standard library `Vec` type. We
|
|---|
| 48 | //! strive to provide all of the `Vec` methods with the same names and
|
|---|
| 49 | //! signatures. The exception is that the element type of some methods will have
|
|---|
| 50 | //! a `Default` bound that's not part of the normal `Vec` type.
|
|---|
| 51 | //!
|
|---|
| 52 | //! The vecs here also have a few additional methods that aren't on the `Vec`
|
|---|
| 53 | //! type. In this case, the names tend to be fairly long so that they are
|
|---|
| 54 | //! unlikely to clash with any future methods added to `Vec`.
|
|---|
| 55 | //!
|
|---|
| 56 | //! ## Stability
|
|---|
| 57 | //! * The `1.0` series of the crate works with Rustc `1.34.0` or later, though
|
|---|
| 58 | //! you still need to have Rustc `1.36.0` to use the `alloc` feature.
|
|---|
| 59 | //! * The `2.0` version of the crate is planned for some time after the
|
|---|
| 60 | //! `min_const_generics` stuff becomes stable. This would greatly raise the
|
|---|
| 61 | //! minimum rust version and also allow us to totally eliminate the need for
|
|---|
| 62 | //! the `Array` trait. The actual usage of the crate is not expected to break
|
|---|
| 63 | //! significantly in this transition.
|
|---|
| 64 |
|
|---|
| 65 | #[allow (unused_imports)]
|
|---|
| 66 | use core::{
|
|---|
| 67 | borrow::{Borrow, BorrowMut},
|
|---|
| 68 | cmp::PartialEq,
|
|---|
| 69 | convert::AsMut,
|
|---|
| 70 | default::Default,
|
|---|
| 71 | fmt::{
|
|---|
| 72 | Binary, Debug, Display, Formatter, LowerExp, LowerHex, Octal, Pointer,
|
|---|
| 73 | UpperExp, UpperHex,
|
|---|
| 74 | },
|
|---|
| 75 | hash::{Hash, Hasher},
|
|---|
| 76 | iter::{Extend, FromIterator, FusedIterator, IntoIterator, Iterator},
|
|---|
| 77 | mem::{needs_drop, replace},
|
|---|
| 78 | ops::{Deref, DerefMut, Index, IndexMut, RangeBounds},
|
|---|
| 79 | slice::SliceIndex,
|
|---|
| 80 | };
|
|---|
| 81 |
|
|---|
| 82 | #[cfg (feature = "alloc" )]
|
|---|
| 83 | #[doc (hidden)] // re-export for macros
|
|---|
| 84 | pub extern crate alloc;
|
|---|
| 85 |
|
|---|
| 86 | mod array;
|
|---|
| 87 | pub use array::*;
|
|---|
| 88 |
|
|---|
| 89 | mod arrayvec;
|
|---|
| 90 | pub use arrayvec::*;
|
|---|
| 91 |
|
|---|
| 92 | mod arrayvec_drain;
|
|---|
| 93 | pub use arrayvec_drain::*;
|
|---|
| 94 |
|
|---|
| 95 | mod slicevec;
|
|---|
| 96 | pub use slicevec::*;
|
|---|
| 97 |
|
|---|
| 98 | #[cfg (feature = "alloc" )]
|
|---|
| 99 | mod tinyvec;
|
|---|
| 100 | #[cfg (feature = "alloc" )]
|
|---|
| 101 | pub use crate::tinyvec::*;
|
|---|
| 102 |
|
|---|
| 103 | // TODO MSRV(1.40.0): Just call the normal `core::mem::take`
|
|---|
| 104 | #[inline (always)]
|
|---|
| 105 | fn take<T: Default>(from: &mut T) -> T {
|
|---|
| 106 | replace(dest:from, T::default())
|
|---|
| 107 | }
|
|---|
| 108 | |
|---|
