]>
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 XL |
52 | //! |
53 | //! [`Arc`]: sync/index.html | |
54 | //! [`Box`]: boxed/index.html | |
55 | //! [`Cell`]: ../core/cell/index.html | |
56 | //! [`Rc`]: rc/index.html | |
57 | //! [`RefCell`]: ../core/cell/index.html | |
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 | #![deny(intra_doc_link_resolution_failure)] // rustdoc is run without -D warnings |
48663c56 | 73 | #![allow(explicit_outlives_requirements)] |
e1599b0c | 74 | #![allow(incomplete_features)] |
f035d41b | 75 | #![deny(unsafe_op_in_unsafe_fn)] |
ea8adc8c | 76 | #![cfg_attr(not(test), feature(generator_trait))] |
b7449926 | 77 | #![cfg_attr(test, feature(test))] |
0531ce1d | 78 | #![feature(allocator_api)] |
041b39d2 | 79 | #![feature(allow_internal_unstable)] |
94b46f34 | 80 | #![feature(arbitrary_self_types)] |
041b39d2 | 81 | #![feature(box_patterns)] |
62682a34 | 82 | #![feature(box_syntax)] |
ba9703b0 | 83 | #![feature(cfg_sanitize)] |
476ff2be | 84 | #![feature(cfg_target_has_atomic)] |
62682a34 | 85 | #![feature(coerce_unsized)] |
f9f354fc | 86 | #![feature(const_btree_new)] |
416331ca XL |
87 | #![feature(const_generic_impls_guard)] |
88 | #![feature(const_generics)] | |
e1599b0c | 89 | #![feature(const_in_array_repeat_expressions)] |
f035d41b | 90 | #![cfg_attr(bootstrap, feature(const_if_match))] |
e74abb32 | 91 | #![feature(cow_is_borrowed)] |
f035d41b | 92 | #![feature(deque_range)] |
a1dfa0c6 | 93 | #![feature(dispatch_from_dyn)] |
62682a34 | 94 | #![feature(core_intrinsics)] |
e1599b0c | 95 | #![feature(container_error_extra)] |
32a655c1 | 96 | #![feature(dropck_eyepatch)] |
041b39d2 | 97 | #![feature(exact_size_is_empty)] |
f9f354fc | 98 | #![feature(extend_one)] |
041b39d2 | 99 | #![feature(fmt_internals)] |
9fa01778 | 100 | #![feature(fn_traits)] |
c34b1796 | 101 | #![feature(fundamental)] |
416331ca | 102 | #![feature(internal_uninit_const)] |
d9579d0f | 103 | #![feature(lang_items)] |
f035d41b | 104 | #![feature(layout_for_ptr)] |
83c7162d | 105 | #![feature(libc)] |
f9f354fc | 106 | #![feature(negative_impls)] |
ba9703b0 | 107 | #![feature(new_uninit)] |
0bf4aa26 | 108 | #![feature(nll)] |
85aaf69f | 109 | #![feature(optin_builtin_traits)] |
ba9703b0 | 110 | #![feature(or_patterns)] |
041b39d2 | 111 | #![feature(pattern)] |
2c00a5a8 | 112 | #![feature(ptr_internals)] |
83c7162d | 113 | #![feature(ptr_offset_from)] |
f035d41b | 114 | #![feature(raw_ref_op)] |
3b2f2976 | 115 | #![feature(rustc_attrs)] |
0731742a | 116 | #![feature(receiver_trait)] |
f9f354fc | 117 | #![feature(min_specialization)] |
62682a34 | 118 | #![feature(staged_api)] |
9fa01778 | 119 | #![feature(std_internals)] |
041b39d2 XL |
120 | #![feature(str_internals)] |
121 | #![feature(trusted_len)] | |
0531ce1d | 122 | #![feature(try_reserve)] |
85aaf69f | 123 | #![feature(unboxed_closures)] |
83c7162d | 124 | #![feature(unicode_internals)] |
f035d41b | 125 | #![feature(unsafe_block_in_unsafe_fn)] |
62682a34 | 126 | #![feature(unsize)] |
532ac7d7 | 127 | #![feature(unsized_locals)] |
3b2f2976 | 128 | #![feature(allocator_internals)] |
0bf4aa26 | 129 | #![feature(slice_partition_dedup)] |
e1599b0c | 130 | #![feature(maybe_uninit_extra, maybe_uninit_slice)] |
a1dfa0c6 | 131 | #![feature(alloc_layout_extra)] |
9fa01778 | 132 | #![feature(try_trait)] |
416331ca | 133 | #![feature(associated_type_bounds)] |
62682a34 | 134 | |
1a4d82fc JJ |
135 | // Allow testing this library |
136 | ||
b039eaaf SL |
137 | #[cfg(test)] |
138 | #[macro_use] | |
139 | extern crate std; | |
041b39d2 XL |
140 | #[cfg(test)] |
141 | extern crate test; | |
142 | ||
476ff2be SL |
143 | // Module with internal macros used by other modules (needs to be included before other modules). |
144 | #[macro_use] | |
145 | mod macros; | |
146 | ||
1a4d82fc JJ |
147 | // Heaps provided for low-level allocation strategies |
148 | ||
83c7162d XL |
149 | pub mod alloc; |
150 | ||
1a4d82fc JJ |
151 | // Primitive types using the heaps above |
152 | ||
c34b1796 AL |
153 | // Need to conditionally define the mod from `boxed.rs` to avoid |
154 | // duplicating the lang-items when building in test cfg; but also need | |
83c7162d | 155 | // to allow code to have `use boxed::Box;` declarations. |
1a4d82fc JJ |
156 | #[cfg(not(test))] |
157 | pub mod boxed; | |
85aaf69f | 158 | #[cfg(test)] |
b039eaaf | 159 | mod boxed { |
83c7162d | 160 | pub use std::boxed::Box; |
b039eaaf | 161 | } |
041b39d2 | 162 | pub mod borrow; |
dfeec247 | 163 | pub mod collections; |
041b39d2 | 164 | pub mod fmt; |
dfeec247 XL |
165 | pub mod prelude; |
166 | pub mod raw_vec; | |
167 | pub mod rc; | |
041b39d2 | 168 | pub mod slice; |
7cac9316 | 169 | pub mod str; |
041b39d2 | 170 | pub mod string; |
dfeec247 XL |
171 | #[cfg(target_has_atomic = "ptr")] |
172 | pub mod sync; | |
ba9703b0 XL |
173 | #[cfg(target_has_atomic = "ptr")] |
174 | pub mod task; | |
dfeec247 XL |
175 | #[cfg(test)] |
176 | mod tests; | |
041b39d2 | 177 | pub mod vec; |
041b39d2 XL |
178 | |
179 | #[cfg(not(test))] | |
180 | mod std { | |
9fa01778 | 181 | pub use core::ops; // RangeFull |
041b39d2 | 182 | } |
e1599b0c XL |
183 | |
184 | #[doc(hidden)] | |
dfeec247 | 185 | #[unstable(feature = "liballoc_internals", issue = "none", reason = "implementation detail")] |
e1599b0c XL |
186 | pub mod __export { |
187 | pub use core::format_args; | |
188 | } |