vendor/tinyvec/src/lib.rs

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