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))]
8pub mod binary_heap;
9#[cfg(not(no_global_oom_handling))]
10mod btree;
11#[cfg(not(no_global_oom_handling))]
12pub mod linked_list;
13#[cfg(not(no_global_oom_handling))]
14pub mod vec_deque;
15
16#[cfg(not(no_global_oom_handling))]
17#[stable(feature = "rust1", since = "1.0.0")]
18pub 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")]
26pub 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)]
35pub use binary_heap::BinaryHeap;
36
37#[cfg(not(no_global_oom_handling))]
38#[stable(feature = "rust1", since = "1.0.0")]
39#[doc(no_inline)]
40pub use btree_map::BTreeMap;
41
42#[cfg(not(no_global_oom_handling))]
43#[stable(feature = "rust1", since = "1.0.0")]
44#[doc(no_inline)]
45pub use btree_set::BTreeSet;
46
47#[cfg(not(no_global_oom_handling))]
48#[stable(feature = "rust1", since = "1.0.0")]
49#[doc(no_inline)]
50pub use linked_list::LinkedList;
51
52#[cfg(not(no_global_oom_handling))]
53#[stable(feature = "rust1", since = "1.0.0")]
54#[doc(no_inline)]
55pub use vec_deque::VecDeque;
56
57use crate::alloc::{Layout, LayoutError};
58use 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")]
63pub struct TryReserveError {
64    kind: TryReserveErrorKind,
65}
66
67impl 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)]
88pub 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)]
116impl 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")]
124impl 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")]
133impl 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)]
153trait 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")]
159impl core::error::Error for TryReserveError {}
160