alloc/collections/
mod.rs

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