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     //! A 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     //! A 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 #[unstable(feature = "try_reserve", reason = "new API", issue = "48043")]
  61 pub struct TryReserveError {
  62     kind: TryReserveErrorKind,
  63 }
  64
  65 impl TryReserveError {
  66     /// Details about the allocation that caused the error
  67     #[inline]
  68     #[unstable(
  69         feature = "try_reserve_kind",
  70         reason = "Uncertain how much info should be exposed",
  71         issue = "48043"
  72     )]
  73     pub fn kind(&self) -> TryReserveErrorKind {
  74         self.kind.clone()
  75     }
  76 }
  77
  78 /// Details of the allocation that caused a `TryReserveError`
  79 #[derive(Clone, PartialEq, Eq, Debug)]
  80 #[unstable(
  81     feature = "try_reserve_kind",
  82     reason = "Uncertain how much info should be exposed",
  83     issue = "48043"
  84 )]
  85 pub enum TryReserveErrorKind {
  86     /// Error due to the computed capacity exceeding the collection's maximum
  87     /// (usually `isize::MAX` bytes).
  88     CapacityOverflow,
  89
  90     /// The memory allocator returned an error
  91     AllocError {
  92         /// The layout of allocation request that failed
  93         layout: Layout,
  94
  95         #[doc(hidden)]
  96         #[unstable(
  97             feature = "container_error_extra",
  98             issue = "none",
  99             reason = "\
 100             Enable exposing the allocator’s custom error value \
 101             if an associated type is added in the future: \
 102             https://github.com/rust-lang/wg-allocators/issues/23"
 103         )]
 104         non_exhaustive: (),
 105     },
 106 }
 107
 108 #[unstable(
 109     feature = "try_reserve_kind",
 110     reason = "Uncertain how much info should be exposed",
 111     issue = "48043"
 112 )]
 113 impl From<TryReserveErrorKind> for TryReserveError {
 114     fn from(kind: TryReserveErrorKind) -> Self {
 115         Self { kind }
 116     }
 117 }
 118
 119 #[unstable(feature = "try_reserve", reason = "new API", issue = "48043")]
 120 impl From<LayoutError> for TryReserveError {
 121     /// Always evaluates to [`TryReserveErrorKind::CapacityOverflow`].
 122     #[inline]
 123     fn from(_: LayoutError) -> Self {
 124         TryReserveErrorKind::CapacityOverflow.into()
 125     }
 126 }
 127
 128 #[unstable(feature = "try_reserve", reason = "new API", issue = "48043")]
 129 impl Display for TryReserveError {
 130     fn fmt(
 131         &self,
 132         fmt: &mut core::fmt::Formatter<'_>,
 133     ) -> core::result::Result<(), core::fmt::Error> {
 134         fmt.write_str("memory allocation failed")?;
 135         let reason = match self.kind {
 136             TryReserveErrorKind::CapacityOverflow => {
 137                 " because the computed capacity exceeded the collection's maximum"
 138             }
 139             TryReserveErrorKind::AllocError { .. } => {
 140                 " because the memory allocator returned a error"
 141             }
 142         };
 143         fmt.write_str(reason)
 144     }
 145 }
 146
 147 /// An intermediate trait for specialization of `Extend`.
 148 #[doc(hidden)]
 149 trait SpecExtend<I: IntoIterator> {
 150     /// Extends `self` with the contents of the given iterator.
 151     fn spec_extend(&mut self, iter: I);
 152 }