alloc/collections/
mod.rs

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

alloc/collections/
mod.rs
