]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | //! # The Rust Core Library |
2 | //! | |
92a42be0 | 3 | //! The Rust Core Library is the dependency-free[^free] foundation of [The |
1a4d82fc JJ |
4 | //! Rust Standard Library](../std/index.html). It is the portable glue |
5 | //! between the language and its libraries, defining the intrinsic and | |
6 | //! primitive building blocks of all Rust code. It links to no | |
7 | //! upstream libraries, no system libraries, and no libc. | |
8 | //! | |
92a42be0 SL |
9 | //! [^free]: Strictly speaking, there are some symbols which are needed but |
10 | //! they aren't always necessary. | |
11 | //! | |
1a4d82fc JJ |
12 | //! The core library is *minimal*: it isn't even aware of heap allocation, |
13 | //! nor does it provide concurrency or I/O. These things require | |
14 | //! platform integration, and this library is platform-agnostic. | |
15 | //! | |
1a4d82fc JJ |
16 | //! # How to use the core library |
17 | //! | |
5bcae85e SL |
18 | //! Please note that all of these details are currently not considered stable. |
19 | //! | |
1a4d82fc JJ |
20 | // FIXME: Fill me in with more detail when the interface settles |
21 | //! This library is built on the assumption of a few existing symbols: | |
22 | //! | |
23 | //! * `memcpy`, `memcmp`, `memset` - These are core memory routines which are | |
24 | //! often generated by LLVM. Additionally, this library can make explicit | |
25 | //! calls to these functions. Their signatures are the same as found in C. | |
26 | //! These functions are often provided by the system libc, but can also be | |
9fa01778 | 27 | //! provided by the [compiler-builtins crate](https://crates.io/crates/compiler_builtins). |
1a4d82fc | 28 | //! |
041b39d2 XL |
29 | //! * `rust_begin_panic` - This function takes four arguments, a |
30 | //! `fmt::Arguments`, a `&'static str`, and two `u32`'s. These four arguments | |
5bcae85e | 31 | //! dictate the panic message, the file at which panic was invoked, and the |
041b39d2 XL |
32 | //! line and column inside the file. It is up to consumers of this core |
33 | //! library to define this panic function; it is only required to never | |
94b46f34 | 34 | //! return. This requires a `lang` attribute named `panic_impl`. |
9e0c209e SL |
35 | //! |
36 | //! * `rust_eh_personality` - is used by the failure mechanisms of the | |
37 | //! compiler. This is often mapped to GCC's personality function, but crates | |
38 | //! which do not trigger a panic can be assured that this function is never | |
39 | //! called. The `lang` attribute is called `eh_personality`. | |
1a4d82fc JJ |
40 | |
41 | // Since libcore defines many fundamental lang items, all tests live in a | |
42 | // separate crate, libcoretest, to avoid bizarre issues. | |
83c7162d XL |
43 | // |
44 | // Here we explicitly #[cfg]-out this whole crate when testing. If we don't do | |
45 | // this, both the generated test artifact and the linked libtest (which | |
46 | // transitively includes libcore) will both define the same set of lang items, | |
dfeec247 | 47 | // and this will cause the E0152 "found duplicate lang item" error. See |
83c7162d XL |
48 | // discussion in #50466 for details. |
49 | // | |
50 | // This cfg won't affect doc tests. | |
51 | #![cfg(not(test))] | |
136023e0 XL |
52 | // To run libcore tests without x.py without ending up with two copies of libcore, Miri needs to be |
53 | // able to "empty" this crate. See <https://github.com/rust-lang/miri-test-libstd/issues/4>. | |
54 | // rustc itself never sets the feature, so this line has no affect there. | |
55 | #![cfg(any(not(feature = "miri-test-libstd"), test, doctest))] | |
92a42be0 | 56 | #![stable(feature = "core", since = "1.6.0")] |
dfeec247 | 57 | #![doc( |
dfeec247 XL |
58 | html_playground_url = "https://play.rust-lang.org/", |
59 | issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", | |
60 | test(no_crate_inject, attr(deny(warnings))), | |
61 | test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))) | |
62 | )] | |
e9174d1e | 63 | #![no_core] |
94222f64 XL |
64 | // |
65 | // Lints: | |
66 | #![deny(rust_2021_incompatible_or_patterns)] | |
67 | #![deny(unsafe_op_in_unsafe_fn)] | |
9fa01778 | 68 | #![warn(deprecated_in_future)] |
9fa01778 | 69 | #![warn(missing_debug_implementations)] |
94222f64 | 70 | #![warn(missing_docs)] |
48663c56 | 71 | #![allow(explicit_outlives_requirements)] |
94222f64 XL |
72 | #![cfg_attr(bootstrap, allow(incomplete_features))] // if_let_guard |
73 | // | |
74 | // Library features for const fns: | |
75 | #![feature(const_align_of_val)] | |
dfeec247 | 76 | #![feature(const_alloc_layout)] |
94222f64 | 77 | #![feature(const_arguments_as_str)] |
fc512014 | 78 | #![feature(const_assert_type)] |
94222f64 XL |
79 | #![feature(const_bigint_helper_methods)] |
80 | #![feature(const_caller_location)] | |
29967ef6 | 81 | #![feature(const_cell_into_inner)] |
94222f64 | 82 | #![feature(const_discriminant)] |
3dfed10e | 83 | #![feature(const_float_bits_conv)] |
94222f64 XL |
84 | #![feature(const_float_classify)] |
85 | #![feature(const_heap)] | |
17df50a5 | 86 | #![feature(const_inherent_unchecked_arith)] |
94222f64 XL |
87 | #![feature(const_int_unchecked_arith)] |
88 | #![feature(const_intrinsic_copy)] | |
89 | #![feature(const_intrinsic_forget)] | |
90 | #![feature(const_likely)] | |
91 | #![feature(const_maybe_uninit_as_ptr)] | |
92 | #![feature(const_maybe_uninit_assume_init)] | |
3dfed10e | 93 | #![feature(const_option)] |
94222f64 | 94 | #![feature(const_pin)] |
f9f354fc | 95 | #![feature(const_ptr_offset)] |
dfeec247 | 96 | #![feature(const_ptr_offset_from)] |
5869c6ff | 97 | #![feature(const_ptr_read)] |
6a06907d | 98 | #![feature(const_ptr_write)] |
3dfed10e | 99 | #![feature(const_raw_ptr_comparison)] |
94222f64 | 100 | #![feature(const_size_of_val)] |
f9f354fc XL |
101 | #![feature(const_slice_from_raw_parts)] |
102 | #![feature(const_slice_ptr_len)] | |
6a06907d | 103 | #![feature(const_swap)] |
94222f64 | 104 | #![feature(const_trait_impl)] |
6c58768f | 105 | #![feature(const_type_id)] |
dfeec247 | 106 | #![feature(const_type_name)] |
3dfed10e | 107 | #![feature(const_unreachable_unchecked)] |
94222f64 XL |
108 | #![feature(const_default_impls)] |
109 | #![feature(duration_consts_2)] | |
110 | #![feature(ptr_metadata)] | |
111 | #![feature(slice_ptr_get)] | |
112 | #![feature(variant_count)] | |
113 | // | |
114 | // Language features: | |
115 | #![feature(abi_unadjusted)] | |
116 | #![feature(allow_internal_unsafe)] | |
117 | #![feature(allow_internal_unstable)] | |
118 | #![feature(asm)] | |
119 | #![feature(associated_type_bounds)] | |
120 | #![feature(auto_traits)] | |
121 | #![feature(cfg_target_has_atomic)] | |
122 | #![feature(const_fn_floating_point_arithmetic)] | |
123 | #![feature(const_fn_fn_ptr_basics)] | |
124 | #![feature(const_fn_trait_bound)] | |
125 | #![cfg_attr(bootstrap, feature(const_fn_transmute))] | |
126 | #![cfg_attr(bootstrap, feature(const_fn_union))] | |
127 | #![feature(const_impl_trait)] | |
128 | #![feature(const_mut_refs)] | |
129 | #![feature(const_panic)] | |
130 | #![feature(const_precise_live_drops)] | |
131 | #![feature(const_raw_ptr_deref)] | |
132 | #![feature(const_refs_to_cell)] | |
416331ca | 133 | #![feature(decl_macro)] |
0531ce1d | 134 | #![feature(doc_cfg)] |
17df50a5 | 135 | #![feature(doc_notable_trait)] |
94222f64 | 136 | #![feature(exhaustive_patterns)] |
83c7162d | 137 | #![feature(extern_types)] |
e9174d1e | 138 | #![feature(fundamental)] |
94222f64 | 139 | #![feature(if_let_guard)] |
6a06907d | 140 | #![feature(intra_doc_pointers)] |
62682a34 SL |
141 | #![feature(intrinsics)] |
142 | #![feature(lang_items)] | |
0531ce1d | 143 | #![feature(link_llvm_intrinsics)] |
ba9703b0 | 144 | #![feature(llvm_asm)] |
94222f64 | 145 | #![feature(min_specialization)] |
f9f354fc | 146 | #![feature(negative_impls)] |
cc61c64b | 147 | #![feature(never_type)] |
e9174d1e | 148 | #![feature(no_core)] |
94222f64 XL |
149 | #![feature(no_coverage)] // rust-lang/rust#84605 |
150 | #![feature(no_niche)] // rust-lang/rust#68303 | |
151 | #![feature(platform_intrinsics)] | |
cc61c64b | 152 | #![feature(prelude_import)] |
94222f64 XL |
153 | #![feature(repr_simd)] |
154 | #![feature(rustc_allow_const_fn_unstable)] | |
54a0048b | 155 | #![feature(rustc_attrs)] |
0531ce1d | 156 | #![feature(simd_ffi)] |
e9174d1e | 157 | #![feature(staged_api)] |
0531ce1d | 158 | #![feature(stmt_expr_attributes)] |
6a06907d | 159 | #![feature(trait_alias)] |
416331ca | 160 | #![feature(transparent_unions)] |
29967ef6 | 161 | #![feature(try_blocks)] |
e9174d1e | 162 | #![feature(unboxed_closures)] |
fc512014 | 163 | #![feature(unsized_fn_params)] |
94222f64 XL |
164 | // |
165 | // Target features: | |
94b46f34 | 166 | #![feature(aarch64_target_feature)] |
94222f64 XL |
167 | #![feature(adx_target_feature)] |
168 | #![feature(arm_target_feature)] | |
0731742a | 169 | #![feature(avx512_target_feature)] |
9fa01778 | 170 | #![feature(cmpxchg16b_target_feature)] |
416331ca XL |
171 | #![feature(f16c_target_feature)] |
172 | #![feature(hexagon_target_feature)] | |
94222f64 XL |
173 | #![feature(mips_target_feature)] |
174 | #![feature(powerpc_target_feature)] | |
175 | #![feature(rtm_target_feature)] | |
176 | #![feature(sse4a_target_feature)] | |
177 | #![feature(tbm_target_feature)] | |
178 | #![feature(wasm_target_feature)] | |
17df50a5 XL |
179 | |
180 | // allow using `core::` in intra-doc links | |
181 | #[allow(unused_extern_crates)] | |
182 | extern crate self as core; | |
ea8adc8c | 183 | |
9e0c209e SL |
184 | #[prelude_import] |
185 | #[allow(unused)] | |
186 | use prelude::v1::*; | |
5bcae85e | 187 | |
e74abb32 | 188 | #[cfg(not(test))] // See #65860 |
1a4d82fc JJ |
189 | #[macro_use] |
190 | mod macros; | |
191 | ||
17df50a5 XL |
192 | // We don't export this through #[macro_export] for now, to avoid breakage. |
193 | // See https://github.com/rust-lang/rust/issues/82913 | |
194 | #[cfg(not(test))] | |
195 | #[unstable(feature = "assert_matches", issue = "82775")] | |
196 | /// Unstable module containing the unstable `assert_matches` macro. | |
197 | pub mod assert_matches { | |
198 | #[unstable(feature = "assert_matches", issue = "82775")] | |
199 | pub use crate::macros::{assert_matches, debug_assert_matches}; | |
200 | } | |
201 | ||
c30ab7b3 SL |
202 | #[macro_use] |
203 | mod internal_macros; | |
204 | ||
1b1a35ee | 205 | #[path = "num/shells/int_macros.rs"] |
1a4d82fc JJ |
206 | #[macro_use] |
207 | mod int_macros; | |
208 | ||
1b1a35ee | 209 | #[path = "num/shells/i128.rs"] |
dfeec247 | 210 | pub mod i128; |
1b1a35ee | 211 | #[path = "num/shells/i16.rs"] |
dfeec247 | 212 | pub mod i16; |
1b1a35ee | 213 | #[path = "num/shells/i32.rs"] |
dfeec247 | 214 | pub mod i32; |
1b1a35ee | 215 | #[path = "num/shells/i64.rs"] |
dfeec247 | 216 | pub mod i64; |
1b1a35ee | 217 | #[path = "num/shells/i8.rs"] |
dfeec247 | 218 | pub mod i8; |
1b1a35ee | 219 | #[path = "num/shells/isize.rs"] |
dfeec247 | 220 | pub mod isize; |
32a655c1 | 221 | |
1b1a35ee | 222 | #[path = "num/shells/u128.rs"] |
dfeec247 | 223 | pub mod u128; |
1b1a35ee | 224 | #[path = "num/shells/u16.rs"] |
dfeec247 | 225 | pub mod u16; |
1b1a35ee | 226 | #[path = "num/shells/u32.rs"] |
dfeec247 | 227 | pub mod u32; |
1b1a35ee | 228 | #[path = "num/shells/u64.rs"] |
dfeec247 | 229 | pub mod u64; |
1b1a35ee | 230 | #[path = "num/shells/u8.rs"] |
dfeec247 | 231 | pub mod u8; |
1b1a35ee | 232 | #[path = "num/shells/usize.rs"] |
dfeec247 | 233 | pub mod usize; |
32a655c1 | 234 | |
dfeec247 XL |
235 | #[path = "num/f32.rs"] |
236 | pub mod f32; | |
237 | #[path = "num/f64.rs"] | |
238 | pub mod f64; | |
1a4d82fc | 239 | |
9346a6ac | 240 | #[macro_use] |
1a4d82fc JJ |
241 | pub mod num; |
242 | ||
243 | /* The libcore prelude, not as all-encompassing as the libstd prelude */ | |
244 | ||
245 | pub mod prelude; | |
246 | ||
247 | /* Core modules for ownership management */ | |
248 | ||
dfeec247 | 249 | pub mod hint; |
1a4d82fc JJ |
250 | pub mod intrinsics; |
251 | pub mod mem; | |
1a4d82fc JJ |
252 | pub mod ptr; |
253 | ||
254 | /* Core language traits */ | |
255 | ||
dfeec247 | 256 | pub mod borrow; |
dfeec247 | 257 | pub mod clone; |
1a4d82fc | 258 | pub mod cmp; |
dfeec247 | 259 | pub mod convert; |
1a4d82fc | 260 | pub mod default; |
dfeec247 XL |
261 | pub mod marker; |
262 | pub mod ops; | |
1a4d82fc JJ |
263 | |
264 | /* Core types and methods on primitives */ | |
265 | ||
266 | pub mod any; | |
c34b1796 | 267 | pub mod array; |
0531ce1d | 268 | pub mod ascii; |
1a4d82fc JJ |
269 | pub mod cell; |
270 | pub mod char; | |
dfeec247 | 271 | pub mod ffi; |
dfeec247 | 272 | pub mod iter; |
3dfed10e XL |
273 | #[unstable(feature = "once_cell", issue = "74465")] |
274 | pub mod lazy; | |
dfeec247 | 275 | pub mod option; |
0531ce1d | 276 | pub mod panic; |
1a4d82fc | 277 | pub mod panicking; |
b7449926 | 278 | pub mod pin; |
1a4d82fc | 279 | pub mod result; |
5869c6ff XL |
280 | #[unstable(feature = "async_stream", issue = "79024")] |
281 | pub mod stream; | |
dfeec247 | 282 | pub mod sync; |
e9174d1e | 283 | |
dfeec247 | 284 | pub mod fmt; |
1a4d82fc | 285 | pub mod hash; |
dfeec247 | 286 | pub mod slice; |
dfeec247 | 287 | pub mod str; |
2c00a5a8 | 288 | pub mod time; |
85aaf69f | 289 | |
83c7162d XL |
290 | pub mod unicode; |
291 | ||
94b46f34 XL |
292 | /* Async */ |
293 | pub mod future; | |
294 | pub mod task; | |
295 | ||
0531ce1d XL |
296 | /* Heap memory allocator trait */ |
297 | #[allow(missing_docs)] | |
83c7162d XL |
298 | pub mod alloc; |
299 | ||
1a4d82fc | 300 | // note: does not need to be public |
e1599b0c | 301 | mod bool; |
1a4d82fc | 302 | mod tuple; |
abe05a73 | 303 | mod unit; |
0531ce1d | 304 | |
74b04a01 XL |
305 | #[stable(feature = "core_primitive", since = "1.43.0")] |
306 | pub mod primitive; | |
307 | ||
9fa01778 | 308 | // Pull in the `core_arch` crate directly into libcore. The contents of |
416331ca | 309 | // `core_arch` are in a different repository: rust-lang/stdarch. |
9fa01778 XL |
310 | // |
311 | // `core_arch` depends on libcore, but the contents of this module are | |
312 | // set up in such a way that directly pulling it here works such that the | |
313 | // crate uses the this crate as its libcore. | |
3dfed10e | 314 | #[path = "../../stdarch/crates/core_arch/src/mod.rs"] |
f035d41b XL |
315 | #[allow( |
316 | missing_docs, | |
317 | missing_debug_implementations, | |
318 | dead_code, | |
319 | unused_imports, | |
320 | unsafe_op_in_unsafe_fn | |
321 | )] | |
17df50a5 | 322 | #[allow(rustdoc::bare_urls)] |
f035d41b XL |
323 | // FIXME: This annotation should be moved into rust-lang/stdarch after clashing_extern_declarations is |
324 | // merged. It currently cannot because bootstrap fails as the lint hasn't been defined yet. | |
3dfed10e | 325 | #[allow(clashing_extern_declarations)] |
0531ce1d | 326 | #[unstable(feature = "stdsimd", issue = "48556")] |
9fa01778 | 327 | mod core_arch; |
0531ce1d | 328 | |
136023e0 | 329 | #[doc = include_str!("../../stdarch/crates/core_arch/src/core_arch_docs.md")] |
83c7162d | 330 | #[stable(feature = "simd_arch", since = "1.27.0")] |
136023e0 XL |
331 | pub mod arch { |
332 | #[stable(feature = "simd_arch", since = "1.27.0")] | |
333 | pub use crate::core_arch::arch::*; | |
334 | ||
335 | /// Inline assembly. | |
336 | /// | |
337 | /// Read the [unstable book] for the usage. | |
338 | /// | |
339 | /// [unstable book]: ../../unstable-book/library-features/asm.html | |
340 | #[unstable( | |
341 | feature = "asm", | |
342 | issue = "72016", | |
343 | reason = "inline assembly is not stable enough for use and is subject to change" | |
344 | )] | |
345 | #[rustc_builtin_macro] | |
346 | pub macro asm("assembly template", $(operands,)* $(options($(option),*))?) { | |
347 | /* compiler built-in */ | |
348 | } | |
349 | ||
350 | /// Module-level inline assembly. | |
351 | #[unstable( | |
352 | feature = "global_asm", | |
353 | issue = "35119", | |
354 | reason = "`global_asm!` is not stable enough for use and is subject to change" | |
355 | )] | |
356 | #[rustc_builtin_macro] | |
357 | pub macro global_asm("assembly template", $(operands,)* $(options($(option),*))?) { | |
358 | /* compiler built-in */ | |
359 | } | |
360 | } |