]>
Commit | Line | Data |
---|---|---|
041b39d2 | 1 | //! # The Rust core allocation and collections library |
1a4d82fc | 2 | //! |
041b39d2 XL |
3 | //! This library provides smart pointers and collections for managing |
4 | //! heap-allocated values. | |
1a4d82fc | 5 | //! |
8faf50e0 XL |
6 | //! This library, like libcore, 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. | |
1a4d82fc | 10 | //! |
1a4d82fc JJ |
11 | //! ## Boxed values |
12 | //! | |
416331ca XL |
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. | |
1a4d82fc | 16 | //! |
bd371182 | 17 | //! This type can be sent among threads efficiently as the size of a `Box` value |
1a4d82fc JJ |
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 | //! | |
416331ca XL |
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. | |
1a4d82fc | 26 | //! |
416331ca XL |
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. | |
1a4d82fc JJ |
30 | //! |
31 | //! ## Atomically reference counted pointers | |
32 | //! | |
416331ca XL |
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. | |
1a4d82fc | 37 | //! |
32a655c1 | 38 | //! This type allows for shared access to the contained data, and is often |
1a4d82fc JJ |
39 | //! paired with synchronization primitives such as mutexes to allow mutation of |
40 | //! shared resources. | |
41 | //! | |
041b39d2 XL |
42 | //! ## Collections |
43 | //! | |
44 | //! Implementations of the most common general purpose data structures are | |
2c00a5a8 | 45 | //! defined in this library. They are re-exported through the |
041b39d2 XL |
46 | //! [standard collections library](../std/collections/index.html). |
47 | //! | |
1a4d82fc JJ |
48 | //! ## Heap interfaces |
49 | //! | |
83c7162d | 50 | //! The [`alloc`](alloc/index.html) module defines the low-level interface to the |
1a4d82fc | 51 | //! default global allocator. It is not compatible with the libc allocator API. |
416331ca | 52 | //! |
3dfed10e XL |
53 | //! [`Arc`]: sync |
54 | //! [`Box`]: boxed | |
55 | //! [`Cell`]: core::cell | |
56 | //! [`Rc`]: rc | |
57 | //! [`RefCell`]: core::cell | |
1a4d82fc | 58 | |
e9174d1e | 59 | #![allow(unused_attributes)] |
48663c56 | 60 | #![stable(feature = "alloc", since = "1.36.0")] |
dfeec247 XL |
61 | #![doc( |
62 | html_root_url = "https://doc.rust-lang.org/nightly/", | |
74b04a01 | 63 | html_playground_url = "https://play.rust-lang.org/", |
dfeec247 XL |
64 | issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", |
65 | test(no_crate_inject, attr(allow(unused_variables), deny(warnings))) | |
66 | )] | |
1a4d82fc | 67 | #![no_std] |
9cc50fc6 | 68 | #![needs_allocator] |
9fa01778 | 69 | #![warn(deprecated_in_future)] |
48663c56 | 70 | #![warn(missing_docs)] |
9fa01778 | 71 | #![warn(missing_debug_implementations)] |
48663c56 | 72 | #![allow(explicit_outlives_requirements)] |
f035d41b | 73 | #![deny(unsafe_op_in_unsafe_fn)] |
fc512014 | 74 | #![feature(rustc_allow_const_fn_unstable)] |
ea8adc8c | 75 | #![cfg_attr(not(test), feature(generator_trait))] |
b7449926 | 76 | #![cfg_attr(test, feature(test))] |
1b1a35ee | 77 | #![cfg_attr(test, feature(new_uninit))] |
0531ce1d | 78 | #![feature(allocator_api)] |
5869c6ff | 79 | #![feature(vec_extend_from_within)] |
3dfed10e | 80 | #![feature(array_chunks)] |
29967ef6 | 81 | #![feature(array_methods)] |
1b1a35ee | 82 | #![feature(array_windows)] |
041b39d2 | 83 | #![feature(allow_internal_unstable)] |
94b46f34 | 84 | #![feature(arbitrary_self_types)] |
5869c6ff | 85 | #![feature(async_stream)] |
041b39d2 | 86 | #![feature(box_patterns)] |
62682a34 | 87 | #![feature(box_syntax)] |
ba9703b0 | 88 | #![feature(cfg_sanitize)] |
476ff2be | 89 | #![feature(cfg_target_has_atomic)] |
62682a34 | 90 | #![feature(coerce_unsized)] |
f9f354fc | 91 | #![feature(const_btree_new)] |
1b1a35ee | 92 | #![feature(const_fn)] |
e74abb32 | 93 | #![feature(cow_is_borrowed)] |
1b1a35ee | 94 | #![feature(const_cow_is_borrowed)] |
6a06907d | 95 | #![feature(destructuring_assignment)] |
a1dfa0c6 | 96 | #![feature(dispatch_from_dyn)] |
62682a34 | 97 | #![feature(core_intrinsics)] |
32a655c1 | 98 | #![feature(dropck_eyepatch)] |
041b39d2 | 99 | #![feature(exact_size_is_empty)] |
3dfed10e | 100 | #![feature(exclusive_range_pattern)] |
f9f354fc | 101 | #![feature(extend_one)] |
041b39d2 | 102 | #![feature(fmt_internals)] |
9fa01778 | 103 | #![feature(fn_traits)] |
c34b1796 | 104 | #![feature(fundamental)] |
1b1a35ee XL |
105 | #![feature(inplace_iteration)] |
106 | #![feature(int_bits_const)] | |
6a06907d XL |
107 | // Technically, this is a bug in rustdoc: rustdoc sees the documentation on `#[lang = slice_alloc]` |
108 | // blocks is for `&[T]`, which also has documentation using this feature in `core`, and gets mad | |
109 | // that the feature-gate isn't enabled. Ideally, it wouldn't check for the feature gate for docs | |
110 | // from other crates, but since this can only appear for lang items, it doesn't seem worth fixing. | |
111 | #![feature(intra_doc_pointers)] | |
d9579d0f | 112 | #![feature(lang_items)] |
f035d41b | 113 | #![feature(layout_for_ptr)] |
1b1a35ee | 114 | #![feature(maybe_uninit_ref)] |
f9f354fc | 115 | #![feature(negative_impls)] |
1b1a35ee | 116 | #![feature(never_type)] |
0bf4aa26 | 117 | #![feature(nll)] |
3dfed10e | 118 | #![feature(nonnull_slice_from_raw_parts)] |
5869c6ff | 119 | #![feature(auto_traits)] |
6a06907d | 120 | #![feature(option_result_unwrap_unchecked)] |
ba9703b0 | 121 | #![feature(or_patterns)] |
041b39d2 | 122 | #![feature(pattern)] |
2c00a5a8 | 123 | #![feature(ptr_internals)] |
3b2f2976 | 124 | #![feature(rustc_attrs)] |
0731742a | 125 | #![feature(receiver_trait)] |
f9f354fc | 126 | #![feature(min_specialization)] |
5869c6ff | 127 | #![feature(set_ptr_value)] |
3dfed10e XL |
128 | #![feature(slice_ptr_get)] |
129 | #![feature(slice_ptr_len)] | |
6a06907d | 130 | #![feature(slice_range)] |
62682a34 | 131 | #![feature(staged_api)] |
041b39d2 XL |
132 | #![feature(str_internals)] |
133 | #![feature(trusted_len)] | |
85aaf69f | 134 | #![feature(unboxed_closures)] |
83c7162d | 135 | #![feature(unicode_internals)] |
6a06907d | 136 | #![cfg_attr(bootstrap, feature(unsafe_block_in_unsafe_fn))] |
62682a34 | 137 | #![feature(unsize)] |
fc512014 | 138 | #![feature(unsized_fn_params)] |
3b2f2976 | 139 | #![feature(allocator_internals)] |
0bf4aa26 | 140 | #![feature(slice_partition_dedup)] |
1b1a35ee | 141 | #![feature(maybe_uninit_extra, maybe_uninit_slice, maybe_uninit_uninit_array)] |
a1dfa0c6 | 142 | #![feature(alloc_layout_extra)] |
1b1a35ee | 143 | #![feature(trusted_random_access)] |
9fa01778 | 144 | #![feature(try_trait)] |
6a06907d XL |
145 | #![cfg_attr(bootstrap, feature(type_alias_impl_trait))] |
146 | #![cfg_attr(not(bootstrap), feature(min_type_alias_impl_trait))] | |
416331ca | 147 | #![feature(associated_type_bounds)] |
5869c6ff XL |
148 | #![feature(slice_group_by)] |
149 | #![feature(decl_macro)] | |
1a4d82fc JJ |
150 | // Allow testing this library |
151 | ||
b039eaaf SL |
152 | #[cfg(test)] |
153 | #[macro_use] | |
154 | extern crate std; | |
041b39d2 XL |
155 | #[cfg(test)] |
156 | extern crate test; | |
157 | ||
476ff2be SL |
158 | // Module with internal macros used by other modules (needs to be included before other modules). |
159 | #[macro_use] | |
160 | mod macros; | |
161 | ||
1a4d82fc JJ |
162 | // Heaps provided for low-level allocation strategies |
163 | ||
83c7162d XL |
164 | pub mod alloc; |
165 | ||
1a4d82fc JJ |
166 | // Primitive types using the heaps above |
167 | ||
c34b1796 AL |
168 | // Need to conditionally define the mod from `boxed.rs` to avoid |
169 | // duplicating the lang-items when building in test cfg; but also need | |
83c7162d | 170 | // to allow code to have `use boxed::Box;` declarations. |
1a4d82fc JJ |
171 | #[cfg(not(test))] |
172 | pub mod boxed; | |
85aaf69f | 173 | #[cfg(test)] |
b039eaaf | 174 | mod boxed { |
83c7162d | 175 | pub use std::boxed::Box; |
b039eaaf | 176 | } |
041b39d2 | 177 | pub mod borrow; |
dfeec247 | 178 | pub mod collections; |
041b39d2 | 179 | pub mod fmt; |
dfeec247 XL |
180 | pub mod prelude; |
181 | pub mod raw_vec; | |
182 | pub mod rc; | |
041b39d2 | 183 | pub mod slice; |
7cac9316 | 184 | pub mod str; |
041b39d2 | 185 | pub mod string; |
dfeec247 XL |
186 | #[cfg(target_has_atomic = "ptr")] |
187 | pub mod sync; | |
ba9703b0 XL |
188 | #[cfg(target_has_atomic = "ptr")] |
189 | pub mod task; | |
dfeec247 XL |
190 | #[cfg(test)] |
191 | mod tests; | |
041b39d2 | 192 | pub mod vec; |
041b39d2 | 193 | |
e1599b0c | 194 | #[doc(hidden)] |
dfeec247 | 195 | #[unstable(feature = "liballoc_internals", issue = "none", reason = "implementation detail")] |
e1599b0c XL |
196 | pub mod __export { |
197 | pub use core::format_args; | |
198 | } |