xref: /openbmc/linux/rust/alloc/collections/mod.rs (revision 3ed03f4d)
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     )]
kind(&self) -> TryReserveErrorKind76     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]
from(kind: TryReserveErrorKind) -> Self118     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]
from(_: LayoutError) -> Self127     fn from(_: LayoutError) -> Self {
128         TryReserveErrorKind::CapacityOverflow
129     }
130 }
131 
132 #[stable(feature = "try_reserve", since = "1.57.0")]
133 impl Display for TryReserveError {
fmt( &self, fmt: &mut core::fmt::Formatter<'_>, ) -> core::result::Result<(), core::fmt::Error>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.
spec_extend(&mut self, iter: I)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 {}
160