library/alloc/src/collections/mod.rs

   1 //! Collection types.
   2
   3 #![stable(feature = "rust1", since = "1.0.0")]
   4
   5 #[cfg(not(no_global_oom_handling))]
   6 pub mod binary_heap;
   7 #[cfg(not(no_global_oom_handling))]
   8 mod btree;
   9 #[cfg(not(no_global_oom_handling))]
  10 pub mod linked_list;
  11 #[cfg(not(no_global_oom_handling))]
  12 pub mod vec_deque;
  13
  14 #[cfg(not(no_global_oom_handling))]
  15 #[stable(feature = "rust1", since = "1.0.0")]
  16 pub mod btree_map {
  17     //! An ordered map based on a B-Tree.
  18     #[stable(feature = "rust1", since = "1.0.0")]
  19     pub use super::btree::map::*;
  20 }
  21
  22 #[cfg(not(no_global_oom_handling))]
  23 #[stable(feature = "rust1", since = "1.0.0")]
  24 pub mod btree_set {
  25     //! An ordered set based on a B-Tree.
  26     #[stable(feature = "rust1", since = "1.0.0")]
  27     pub use super::btree::set::*;
  28 }
  29
  30 #[cfg(not(no_global_oom_handling))]
  31 #[stable(feature = "rust1", since = "1.0.0")]
  32 #[doc(no_inline)]
  33 pub use binary_heap::BinaryHeap;
  34
  35 #[cfg(not(no_global_oom_handling))]
  36 #[stable(feature = "rust1", since = "1.0.0")]
  37 #[doc(no_inline)]
  38 pub use btree_map::BTreeMap;
  39
  40 #[cfg(not(no_global_oom_handling))]
  41 #[stable(feature = "rust1", since = "1.0.0")]
  42 #[doc(no_inline)]
  43 pub use btree_set::BTreeSet;
  44
  45 #[cfg(not(no_global_oom_handling))]
  46 #[stable(feature = "rust1", since = "1.0.0")]
  47 #[doc(no_inline)]
  48 pub use linked_list::LinkedList;
  49
  50 #[cfg(not(no_global_oom_handling))]
  51 #[stable(feature = "rust1", since = "1.0.0")]
  52 #[doc(no_inline)]
  53 pub use vec_deque::VecDeque;
  54
  55 use crate::alloc::{Layout, LayoutError};
  56 use core::fmt::Display;
  57
  58 /// The error type for `try_reserve` methods.
  59 #[derive(Clone, PartialEq, Eq, Debug)]
  60 #[stable(feature = "try_reserve", since = "1.57.0")]
  61 pub struct TryReserveError {
  62     kind: TryReserveErrorKind,
  63 }
  64
  65 impl TryReserveError {
  66     /// Details about the allocation that caused the error
  67     #[inline]
  68     #[must_use]
  69     #[unstable(
  70         feature = "try_reserve_kind",
  71         reason = "Uncertain how much info should be exposed",
  72         issue = "48043"
  73     )]
  74     pub fn kind(&self) -> TryReserveErrorKind {
  75         self.kind.clone()
  76     }
  77 }
  78
  79 /// Details of the allocation that caused a `TryReserveError`
  80 #[derive(Clone, PartialEq, Eq, Debug)]
  81 #[unstable(
  82     feature = "try_reserve_kind",
  83     reason = "Uncertain how much info should be exposed",
  84     issue = "48043"
  85 )]
  86 pub enum TryReserveErrorKind {
  87     /// Error due to the computed capacity exceeding the collection's maximum
  88     /// (usually `isize::MAX` bytes).
  89     CapacityOverflow,
  90
  91     /// The memory allocator returned an error
  92     AllocError {
  93         /// The layout of allocation request that failed
  94         layout: Layout,
  95
  96         #[doc(hidden)]
  97         #[unstable(
  98             feature = "container_error_extra",
  99             issue = "none",
 100             reason = "\
 101             Enable exposing the allocator’s custom error value \
 102             if an associated type is added in the future: \
 103             https://github.com/rust-lang/wg-allocators/issues/23"
 104         )]
 105         non_exhaustive: (),
 106     },
 107 }
 108
 109 #[unstable(
 110     feature = "try_reserve_kind",
 111     reason = "Uncertain how much info should be exposed",
 112     issue = "48043"
 113 )]
 114 impl From<TryReserveErrorKind> for TryReserveError {
 115     #[inline]
 116     fn from(kind: TryReserveErrorKind) -> Self {
 117         Self { kind }
 118     }
 119 }
 120
 121 #[unstable(feature = "try_reserve_kind", reason = "new API", issue = "48043")]
 122 impl From<LayoutError> for TryReserveErrorKind {
 123     /// Always evaluates to [`TryReserveErrorKind::CapacityOverflow`].
 124     #[inline]
 125     fn from(_: LayoutError) -> Self {
 126         TryReserveErrorKind::CapacityOverflow
 127     }
 128 }
 129
 130 #[stable(feature = "try_reserve", since = "1.57.0")]
 131 impl Display for TryReserveError {
 132     fn fmt(
 133         &self,
 134         fmt: &mut core::fmt::Formatter<'_>,
 135     ) -> core::result::Result<(), core::fmt::Error> {
 136         fmt.write_str("memory allocation failed")?;
 137         let reason = match self.kind {
 138             TryReserveErrorKind::CapacityOverflow => {
 139                 " because the computed capacity exceeded the collection's maximum"
 140             }
 141             TryReserveErrorKind::AllocError { .. } => {
 142                 " because the memory allocator returned a error"
 143             }
 144         };
 145         fmt.write_str(reason)
 146     }
 147 }
 148
 149 /// An intermediate trait for specialization of `Extend`.
 150 #[doc(hidden)]
 151 trait SpecExtend<I: IntoIterator> {
 152     /// Extends `self` with the contents of the given iterator.
 153     fn spec_extend(&mut self, iter: I);
 154 }