rust/alloc/collections/mod.rs

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