1 | //! # The Rust core allocation and collections library |
2 | //! |
3 | //! This library provides smart pointers and collections for managing |
4 | //! heap-allocated values. |
5 | //! |
6 | //! This library, like core, normally doesn’t need to be used directly |
7 | //! since its contents are re-exported in the [`std` crate](../std/index.html). |
8 | //! Crates that use the `#![no_std]` attribute however will typically |
9 | //! not depend on `std`, so they’d use this crate instead. |
10 | //! |
11 | //! ## Boxed values |
12 | //! |
13 | //! The [`Box`] type is a smart pointer type. There can only be one owner of a |
14 | //! [`Box`], and the owner can decide to mutate the contents, which live on the |
15 | //! heap. |
16 | //! |
17 | //! This type can be sent among threads efficiently as the size of a `Box` value |
18 | //! is the same as that of a pointer. Tree-like data structures are often built |
19 | //! with boxes because each node often has only one owner, the parent. |
20 | //! |
21 | //! ## Reference counted pointers |
22 | //! |
23 | //! The [`Rc`] type is a non-threadsafe reference-counted pointer type intended |
24 | //! for sharing memory within a thread. An [`Rc`] pointer wraps a type, `T`, and |
25 | //! only allows access to `&T`, a shared reference. |
26 | //! |
27 | //! This type is useful when inherited mutability (such as using [`Box`]) is too |
28 | //! constraining for an application, and is often paired with the [`Cell`] or |
29 | //! [`RefCell`] types in order to allow mutation. |
30 | //! |
31 | //! ## Atomically reference counted pointers |
32 | //! |
33 | //! The [`Arc`] type is the threadsafe equivalent of the [`Rc`] type. It |
34 | //! provides all the same functionality of [`Rc`], except it requires that the |
35 | //! contained type `T` is shareable. Additionally, [`Arc<T>`][`Arc`] is itself |
36 | //! sendable while [`Rc<T>`][`Rc`] is not. |
37 | //! |
38 | //! This type allows for shared access to the contained data, and is often |
39 | //! paired with synchronization primitives such as mutexes to allow mutation of |
40 | //! shared resources. |
41 | //! |
42 | //! ## Collections |
43 | //! |
44 | //! Implementations of the most common general purpose data structures are |
45 | //! defined in this library. They are re-exported through the |
46 | //! [standard collections library](../std/collections/index.html). |
47 | //! |
48 | //! ## Heap interfaces |
49 | //! |
50 | //! The [`alloc`](alloc/index.html) module defines the low-level interface to the |
51 | //! default global allocator. It is not compatible with the libc allocator API. |
52 | //! |
53 | //! [`Arc`]: sync |
54 | //! [`Box`]: boxed |
55 | //! [`Cell`]: core::cell |
56 | //! [`Rc`]: rc |
57 | //! [`RefCell`]: core::cell |
58 | |
59 | #![allow (incomplete_features)] |
60 | #![allow (unused_attributes)] |
61 | #![stable (feature = "alloc" , since = "1.36.0" )] |
62 | #![doc ( |
63 | html_playground_url = "https://play.rust-lang.org/" , |
64 | issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/" , |
65 | test(no_crate_inject, attr(allow(unused_variables), deny(warnings))) |
66 | )] |
67 | #![doc (cfg_hide( |
68 | not(test), |
69 | no_global_oom_handling, |
70 | not(no_global_oom_handling), |
71 | not(no_rc), |
72 | not(no_sync), |
73 | target_has_atomic = "ptr" |
74 | ))] |
75 | #![doc (rust_logo)] |
76 | #![feature (rustdoc_internals)] |
77 | #![no_std ] |
78 | #![needs_allocator ] |
79 | // Lints: |
80 | #![deny (unsafe_op_in_unsafe_fn)] |
81 | #![deny (fuzzy_provenance_casts)] |
82 | #![warn (deprecated_in_future)] |
83 | #![warn (missing_debug_implementations)] |
84 | #![warn (missing_docs)] |
85 | #![allow (explicit_outlives_requirements)] |
86 | #![warn (multiple_supertrait_upcastable)] |
87 | #![allow (internal_features)] |
88 | #![allow (rustdoc::redundant_explicit_links)] |
89 | #![warn (rustdoc::unescaped_backticks)] |
90 | #![deny (ffi_unwind_calls)] |
91 | #![warn (unreachable_pub)] |
92 | // |
93 | // Library features: |
94 | // tidy-alphabetical-start |
95 | #![feature (alloc_layout_extra)] |
96 | #![feature (allocator_api)] |
97 | #![feature (array_chunks)] |
98 | #![feature (array_into_iter_constructors)] |
99 | #![feature (array_windows)] |
100 | #![feature (ascii_char)] |
101 | #![feature (assert_matches)] |
102 | #![feature (async_fn_traits)] |
103 | #![feature (async_iterator)] |
104 | #![feature (bstr)] |
105 | #![feature (bstr_internals)] |
106 | #![feature (char_internals)] |
107 | #![feature (char_max_len)] |
108 | #![feature (clone_to_uninit)] |
109 | #![feature (coerce_unsized)] |
110 | #![feature (const_eval_select)] |
111 | #![feature (const_heap)] |
112 | #![feature (core_intrinsics)] |
113 | #![feature (deprecated_suggestion)] |
114 | #![feature (deref_pure_trait)] |
115 | #![feature (dispatch_from_dyn)] |
116 | #![feature (ergonomic_clones)] |
117 | #![feature (error_generic_member_access)] |
118 | #![feature (exact_size_is_empty)] |
119 | #![feature (extend_one)] |
120 | #![feature (extend_one_unchecked)] |
121 | #![feature (fmt_internals)] |
122 | #![feature (fn_traits)] |
123 | #![feature (formatting_options)] |
124 | #![feature (generic_atomic)] |
125 | #![feature (hasher_prefixfree_extras)] |
126 | #![feature (inplace_iteration)] |
127 | #![feature (iter_advance_by)] |
128 | #![feature (iter_next_chunk)] |
129 | #![feature (layout_for_ptr)] |
130 | #![feature (legacy_receiver_trait)] |
131 | #![feature (local_waker)] |
132 | #![feature (maybe_uninit_slice)] |
133 | #![feature (maybe_uninit_uninit_array_transpose)] |
134 | #![feature (panic_internals)] |
135 | #![feature (pattern)] |
136 | #![feature (pin_coerce_unsized_trait)] |
137 | #![feature (pointer_like_trait)] |
138 | #![feature (ptr_alignment_type)] |
139 | #![feature (ptr_internals)] |
140 | #![feature (ptr_metadata)] |
141 | #![feature (set_ptr_value)] |
142 | #![feature (sized_type_properties)] |
143 | #![feature (slice_from_ptr_range)] |
144 | #![feature (slice_index_methods)] |
145 | #![feature (slice_iter_mut_as_mut_slice)] |
146 | #![feature (slice_ptr_get)] |
147 | #![feature (slice_range)] |
148 | #![feature (std_internals)] |
149 | #![feature (str_internals)] |
150 | #![feature (temporary_niche_types)] |
151 | #![feature (trusted_fused)] |
152 | #![feature (trusted_len)] |
153 | #![feature (trusted_random_access)] |
154 | #![feature (try_trait_v2)] |
155 | #![feature (try_with_capacity)] |
156 | #![feature (tuple_trait)] |
157 | #![feature (unicode_internals)] |
158 | #![feature (unsize)] |
159 | #![feature (unwrap_infallible)] |
160 | // tidy-alphabetical-end |
161 | // |
162 | // Language features: |
163 | // tidy-alphabetical-start |
164 | #![feature (allocator_internals)] |
165 | #![feature (allow_internal_unstable)] |
166 | #![feature (cfg_sanitize)] |
167 | #![feature (const_precise_live_drops)] |
168 | #![feature (coroutine_trait)] |
169 | #![feature (decl_macro)] |
170 | #![feature (dropck_eyepatch)] |
171 | #![feature (fundamental)] |
172 | #![feature (hashmap_internals)] |
173 | #![feature (intrinsics)] |
174 | #![feature (lang_items)] |
175 | #![feature (min_specialization)] |
176 | #![feature (multiple_supertrait_upcastable)] |
177 | #![feature (negative_impls)] |
178 | #![feature (never_type)] |
179 | #![feature (optimize_attribute)] |
180 | #![feature (rustc_allow_const_fn_unstable)] |
181 | #![feature (rustc_attrs)] |
182 | #![feature (slice_internals)] |
183 | #![feature (staged_api)] |
184 | #![feature (stmt_expr_attributes)] |
185 | #![feature (strict_provenance_lints)] |
186 | #![feature (unboxed_closures)] |
187 | #![feature (unsized_fn_params)] |
188 | #![feature (with_negative_coherence)] |
189 | #![rustc_preserve_ub_checks] |
190 | // tidy-alphabetical-end |
191 | // |
192 | // Rustdoc features: |
193 | #![feature (doc_cfg)] |
194 | #![feature (doc_cfg_hide)] |
195 | // Technically, this is a bug in rustdoc: rustdoc sees the documentation on `#[lang = slice_alloc]` |
196 | // blocks is for `&[T]`, which also has documentation using this feature in `core`, and gets mad |
197 | // that the feature-gate isn't enabled. Ideally, it wouldn't check for the feature gate for docs |
198 | // from other crates, but since this can only appear for lang items, it doesn't seem worth fixing. |
199 | #![feature (intra_doc_pointers)] |
200 | |
201 | // Module with internal macros used by other modules (needs to be included before other modules). |
202 | #[macro_use ] |
203 | mod macros; |
204 | |
205 | mod raw_vec; |
206 | |
207 | // Heaps provided for low-level allocation strategies |
208 | pub mod alloc; |
209 | |
210 | // Primitive types using the heaps above |
211 | |
212 | // Need to conditionally define the mod from `boxed.rs` to avoid |
213 | // duplicating the lang-items when building in test cfg; but also need |
214 | // to allow code to have `use boxed::Box;` declarations. |
215 | pub mod borrow; |
216 | pub mod boxed; |
217 | #[unstable (feature = "bstr" , issue = "134915" )] |
218 | pub mod bstr; |
219 | pub mod collections; |
220 | #[cfg (all(not(no_rc), not(no_sync), not(no_global_oom_handling)))] |
221 | pub mod ffi; |
222 | pub mod fmt; |
223 | #[cfg (not(no_rc))] |
224 | pub mod rc; |
225 | pub mod slice; |
226 | pub mod str; |
227 | pub mod string; |
228 | #[cfg (all(not(no_rc), not(no_sync), target_has_atomic = "ptr" ))] |
229 | pub mod sync; |
230 | #[cfg (all(not(no_global_oom_handling), not(no_rc), not(no_sync)))] |
231 | pub mod task; |
232 | pub mod vec; |
233 | |
234 | #[doc (hidden)] |
235 | #[unstable (feature = "liballoc_internals" , issue = "none" , reason = "implementation detail" )] |
236 | pub mod __export { |
237 | pub use core::format_args; |
238 | pub use core::hint::must_use; |
239 | } |
240 | |