]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT |
2 | // file at the top-level directory of this distribution and at | |
3 | // http://rust-lang.org/COPYRIGHT. | |
4 | // | |
5 | // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or | |
6 | // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license | |
7 | // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your | |
8 | // option. This file may not be copied, modified, or distributed | |
9 | // except according to those terms. | |
10 | ||
11 | //! # The Rust Standard Library | |
12 | //! | |
13 | //! The Rust Standard Library provides the essential runtime | |
14 | //! functionality for building portable Rust software. | |
1a4d82fc | 15 | //! |
bd371182 AL |
16 | //! The rust standard library is available to all rust crates by |
17 | //! default, just as if contained an `extern crate std` import at the | |
18 | //! crate root. Therefore the standard library can be accessed in | |
19 | //! `use` statements through the path `std`, as in `use std::thread`, | |
20 | //! or in expressions through the absolute path `::std`, as in | |
21 | //! `::std::thread::sleep_ms(100)`. | |
1a4d82fc | 22 | //! |
bd371182 AL |
23 | //! Furthermore, the standard library defines [The Rust |
24 | //! Prelude](prelude/index.html), a small collection of items, mostly | |
25 | //! traits, that are imported into and available in every module. | |
1a4d82fc | 26 | //! |
bd371182 | 27 | //! ## What is in the standard library |
1a4d82fc | 28 | //! |
bd371182 AL |
29 | //! The standard library is minimal, a set of battle-tested |
30 | //! core types and shared abstractions for the [broader Rust | |
d9579d0f | 31 | //! ecosystem](https://crates.io) to build on. |
1a4d82fc | 32 | //! |
bd371182 AL |
33 | //! The [primitive types](#primitives), though not defined in the |
34 | //! standard library, are documented here, as are the predefined | |
35 | //! [macros](#macros). | |
1a4d82fc | 36 | //! |
bd371182 | 37 | //! ## Containers and collections |
1a4d82fc | 38 | //! |
bd371182 AL |
39 | //! The [`option`](option/index.html) and |
40 | //! [`result`](result/index.html) modules define optional and | |
41 | //! error-handling types, `Option` and `Result`. The | |
42 | //! [`iter`](iter/index.html) module defines Rust's iterator trait, | |
d9579d0f | 43 | //! [`Iterator`](iter/trait.Iterator.html), which works with the `for` |
bd371182 | 44 | //! loop to access collections. |
1a4d82fc | 45 | //! |
c34b1796 AL |
46 | //! The common container type, `Vec`, a growable vector backed by an array, |
47 | //! lives in the [`vec`](vec/index.html) module. Contiguous, unsized regions | |
48 | //! of memory, `[T]`, commonly called "slices", and their borrowed versions, | |
49 | //! `&[T]`, commonly called "borrowed slices", are built-in types for which the | |
50 | //! [`slice`](slice/index.html) module defines many methods. | |
1a4d82fc JJ |
51 | //! |
52 | //! `&str`, a UTF-8 string, is a built-in type, and the standard library | |
53 | //! defines methods for it on a variety of traits in the | |
54 | //! [`str`](str/index.html) module. Rust strings are immutable; | |
55 | //! use the `String` type defined in [`string`](string/index.html) | |
56 | //! for a mutable string builder. | |
57 | //! | |
58 | //! For converting to strings use the [`format!`](fmt/index.html) | |
59 | //! macro, and for converting from strings use the | |
60 | //! [`FromStr`](str/trait.FromStr.html) trait. | |
61 | //! | |
bd371182 AL |
62 | //! Data may be shared by placing it in a reference-counted box or the |
63 | //! [`Rc`][rc/index.html] type, and if further contained in a [`Cell` | |
64 | //! or `RefCell`](cell/index.html), may be mutated as well as shared. | |
65 | //! Likewise, in a concurrent setting it is common to pair an | |
66 | //! atomically-reference-counted box, [`Arc`](sync/struct.Arc.html), | |
67 | //! with a [`Mutex`](sync/struct.Mutex.html) to get the same effect. | |
68 | //! | |
69 | //! The [`collections`](collections/index.html) module defines maps, | |
70 | //! sets, linked lists and other typical collection types, including | |
71 | //! the common [`HashMap`](collections/struct.HashMap.html). | |
72 | //! | |
73 | //! ## Platform abstractions and I/O | |
1a4d82fc JJ |
74 | //! |
75 | //! Besides basic data types, the standard library is largely concerned | |
76 | //! with abstracting over differences in common platforms, most notably | |
bd371182 AL |
77 | //! Windows and Unix derivatives. |
78 | //! | |
79 | //! Common types of I/O, including [files](fs/struct.File.html), | |
80 | //! [TCP](net/struct.TcpStream.html), | |
81 | //! [UDP](net/struct.UdpSocket.html), are defined in the | |
82 | //! [`io`](io/index.html), [`fs`](fs/index.html), and | |
83 | //! [`net`](net/index.html) modules. | |
84 | //! | |
85 | //! The [`thread`](thread/index.html) module contains Rust's threading | |
86 | //! abstractions. [`sync`](sync/index.html) contains further | |
87 | //! primitive shared memory types, including | |
88 | //! [`atomic`](sync/atomic/index.html) and | |
89 | //! [`mpsc`](sync/mpsc/index.html), which contains the channel types | |
90 | //! for message passing. | |
91 | ||
c34b1796 AL |
92 | // Do not remove on snapshot creation. Needed for bootstrap. (Issue #22364) |
93 | #![cfg_attr(stage0, feature(custom_attribute))] | |
1a4d82fc | 94 | #![crate_name = "std"] |
85aaf69f | 95 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
96 | #![staged_api] |
97 | #![crate_type = "rlib"] | |
98 | #![crate_type = "dylib"] | |
99 | #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png", | |
100 | html_favicon_url = "http://www.rust-lang.org/favicon.ico", | |
101 | html_root_url = "http://doc.rust-lang.org/nightly/", | |
102 | html_playground_url = "http://play.rust-lang.org/")] | |
9346a6ac AL |
103 | #![doc(test(no_crate_inject, attr(deny(warnings))))] |
104 | #![doc(test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))))] | |
1a4d82fc | 105 | |
85aaf69f | 106 | #![feature(alloc)] |
d9579d0f AL |
107 | #![feature(allow_internal_unstable)] |
108 | #![feature(associated_consts)] | |
1a4d82fc | 109 | #![feature(box_syntax)] |
85aaf69f SL |
110 | #![feature(collections)] |
111 | #![feature(core)] | |
d9579d0f AL |
112 | #![feature(debug_builders)] |
113 | #![feature(into_cow)] | |
85aaf69f SL |
114 | #![feature(lang_items)] |
115 | #![feature(libc)] | |
116 | #![feature(linkage, thread_local, asm)] | |
d9579d0f | 117 | #![feature(macro_reexport)] |
85aaf69f SL |
118 | #![feature(optin_builtin_traits)] |
119 | #![feature(rand)] | |
d9579d0f | 120 | #![feature(slice_patterns)] |
85aaf69f | 121 | #![feature(staged_api)] |
d9579d0f AL |
122 | #![feature(std_misc)] |
123 | #![feature(str_char)] | |
85aaf69f SL |
124 | #![feature(unboxed_closures)] |
125 | #![feature(unicode)] | |
c34b1796 | 126 | #![feature(unique)] |
d9579d0f | 127 | #![feature(unsafe_no_drop_flag, filling_drop)] |
9346a6ac AL |
128 | #![feature(zero_one)] |
129 | #![cfg_attr(test, feature(float_from_str_radix))] | |
c34b1796 | 130 | #![cfg_attr(test, feature(test, rustc_private, std_misc))] |
1a4d82fc JJ |
131 | |
132 | // Don't link to std. We are std. | |
85aaf69f | 133 | #![feature(no_std)] |
1a4d82fc JJ |
134 | #![no_std] |
135 | ||
c34b1796 | 136 | #![allow(trivial_casts)] |
1a4d82fc JJ |
137 | #![deny(missing_docs)] |
138 | ||
85aaf69f SL |
139 | #[cfg(test)] extern crate test; |
140 | #[cfg(test)] #[macro_use] extern crate log; | |
1a4d82fc JJ |
141 | |
142 | #[macro_use] | |
85aaf69f SL |
143 | #[macro_reexport(assert, assert_eq, debug_assert, debug_assert_eq, |
144 | unreachable, unimplemented, write, writeln)] | |
1a4d82fc JJ |
145 | extern crate core; |
146 | ||
147 | #[macro_use] | |
85aaf69f | 148 | #[macro_reexport(vec, format)] |
c34b1796 | 149 | extern crate collections as core_collections; |
1a4d82fc | 150 | |
c34b1796 | 151 | #[allow(deprecated)] extern crate rand as core_rand; |
1a4d82fc | 152 | extern crate alloc; |
d9579d0f | 153 | extern crate rustc_unicode; |
1a4d82fc JJ |
154 | extern crate libc; |
155 | ||
85aaf69f SL |
156 | #[macro_use] #[no_link] extern crate rustc_bitflags; |
157 | ||
1a4d82fc | 158 | // Make std testable by not duplicating lang items. See #2912 |
c34b1796 | 159 | #[cfg(test)] extern crate std as realstd; |
1a4d82fc JJ |
160 | #[cfg(test)] pub use realstd::marker; |
161 | #[cfg(test)] pub use realstd::ops; | |
162 | #[cfg(test)] pub use realstd::cmp; | |
163 | #[cfg(test)] pub use realstd::boxed; | |
164 | ||
165 | ||
166 | // NB: These reexports are in the order they should be listed in rustdoc | |
167 | ||
168 | pub use core::any; | |
1a4d82fc JJ |
169 | pub use core::cell; |
170 | pub use core::clone; | |
171 | #[cfg(not(test))] pub use core::cmp; | |
c34b1796 | 172 | pub use core::convert; |
1a4d82fc | 173 | pub use core::default; |
1a4d82fc JJ |
174 | pub use core::hash; |
175 | pub use core::intrinsics; | |
176 | pub use core::iter; | |
177 | #[cfg(not(test))] pub use core::marker; | |
178 | pub use core::mem; | |
179 | #[cfg(not(test))] pub use core::ops; | |
180 | pub use core::ptr; | |
181 | pub use core::raw; | |
182 | pub use core::simd; | |
183 | pub use core::result; | |
184 | pub use core::option; | |
c34b1796 | 185 | pub mod error; |
1a4d82fc JJ |
186 | |
187 | #[cfg(not(test))] pub use alloc::boxed; | |
188 | pub use alloc::rc; | |
189 | ||
85aaf69f SL |
190 | pub use core_collections::borrow; |
191 | pub use core_collections::fmt; | |
1a4d82fc JJ |
192 | pub use core_collections::slice; |
193 | pub use core_collections::str; | |
194 | pub use core_collections::string; | |
85aaf69f | 195 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
196 | pub use core_collections::vec; |
197 | ||
d9579d0f | 198 | pub use rustc_unicode::char; |
1a4d82fc JJ |
199 | |
200 | /* Exported macros */ | |
201 | ||
202 | #[macro_use] | |
203 | mod macros; | |
204 | ||
1a4d82fc JJ |
205 | mod rtdeps; |
206 | ||
207 | /* The Prelude. */ | |
208 | ||
209 | pub mod prelude; | |
210 | ||
211 | ||
212 | /* Primitive types */ | |
213 | ||
c34b1796 AL |
214 | // NB: slice and str are primitive types too, but their module docs + primitive doc pages |
215 | // are inlined from the public re-exports of core_collections::{slice, str} above. | |
216 | ||
1a4d82fc JJ |
217 | #[path = "num/float_macros.rs"] |
218 | #[macro_use] | |
219 | mod float_macros; | |
220 | ||
221 | #[path = "num/int_macros.rs"] | |
222 | #[macro_use] | |
223 | mod int_macros; | |
224 | ||
225 | #[path = "num/uint_macros.rs"] | |
226 | #[macro_use] | |
227 | mod uint_macros; | |
228 | ||
1a4d82fc JJ |
229 | #[path = "num/isize.rs"] pub mod isize; |
230 | #[path = "num/i8.rs"] pub mod i8; | |
231 | #[path = "num/i16.rs"] pub mod i16; | |
232 | #[path = "num/i32.rs"] pub mod i32; | |
233 | #[path = "num/i64.rs"] pub mod i64; | |
234 | ||
1a4d82fc JJ |
235 | #[path = "num/usize.rs"] pub mod usize; |
236 | #[path = "num/u8.rs"] pub mod u8; | |
237 | #[path = "num/u16.rs"] pub mod u16; | |
238 | #[path = "num/u32.rs"] pub mod u32; | |
239 | #[path = "num/u64.rs"] pub mod u64; | |
240 | ||
241 | #[path = "num/f32.rs"] pub mod f32; | |
242 | #[path = "num/f64.rs"] pub mod f64; | |
243 | ||
244 | pub mod ascii; | |
c34b1796 | 245 | |
1a4d82fc JJ |
246 | pub mod thunk; |
247 | ||
248 | /* Common traits */ | |
249 | ||
1a4d82fc JJ |
250 | pub mod num; |
251 | ||
252 | /* Runtime and platform support */ | |
253 | ||
254 | #[macro_use] | |
c34b1796 | 255 | pub mod thread; |
1a4d82fc | 256 | |
c34b1796 | 257 | pub mod collections; |
1a4d82fc | 258 | pub mod dynamic_lib; |
c34b1796 | 259 | pub mod env; |
1a4d82fc | 260 | pub mod ffi; |
85aaf69f | 261 | pub mod fs; |
c34b1796 | 262 | pub mod io; |
85aaf69f | 263 | pub mod net; |
1a4d82fc JJ |
264 | pub mod os; |
265 | pub mod path; | |
85aaf69f | 266 | pub mod process; |
c34b1796 | 267 | pub mod sync; |
1a4d82fc JJ |
268 | pub mod time; |
269 | ||
c34b1796 AL |
270 | #[macro_use] |
271 | #[path = "sys/common/mod.rs"] mod sys_common; | |
1a4d82fc JJ |
272 | |
273 | #[cfg(unix)] | |
274 | #[path = "sys/unix/mod.rs"] mod sys; | |
275 | #[cfg(windows)] | |
276 | #[path = "sys/windows/mod.rs"] mod sys; | |
277 | ||
1a4d82fc | 278 | pub mod rt; |
85aaf69f | 279 | mod panicking; |
9346a6ac AL |
280 | mod rand; |
281 | ||
282 | // Some external utilities of the standard library rely on randomness (aka | |
283 | // rustc_back::TempDir and tests) and need a way to get at the OS rng we've got | |
284 | // here. This module is not at all intended for stabilization as-is, however, | |
285 | // but it may be stabilized long-term. As a result we're exposing a hidden, | |
286 | // unstable module so we can get our build working. | |
287 | #[doc(hidden)] | |
288 | #[unstable(feature = "rand")] | |
289 | pub mod __rand { | |
290 | pub use rand::{thread_rng, ThreadRng, Rng}; | |
291 | } | |
1a4d82fc | 292 | |
c34b1796 | 293 | // Modules that exist purely to document + host impl docs for primitive types |
1a4d82fc | 294 | |
c34b1796 | 295 | mod array; |
1a4d82fc JJ |
296 | mod bool; |
297 | mod unit; | |
298 | mod tuple; | |
299 | ||
300 | // A curious inner-module that's not exported that contains the binding | |
301 | // 'std' so that macro-expanded references to std::error and such | |
302 | // can be resolved within libstd. | |
303 | #[doc(hidden)] | |
304 | mod std { | |
1a4d82fc JJ |
305 | pub use sync; // used for select!() |
306 | pub use error; // used for try!() | |
307 | pub use fmt; // used for any formatting strings | |
d9579d0f | 308 | pub use option; // used for thread_local!{} |
1a4d82fc JJ |
309 | pub use rt; // used for panic!() |
310 | pub use vec; // used for vec![] | |
311 | pub use cell; // used for tls! | |
c34b1796 | 312 | pub use thread; // used for thread_local! |
1a4d82fc | 313 | pub use marker; // used for tls! |
1a4d82fc | 314 | |
85aaf69f SL |
315 | // The test runner calls ::std::env::args() but really wants realstd |
316 | #[cfg(test)] pub use realstd::env as env; | |
1a4d82fc JJ |
317 | // The test runner requires std::slice::Vector, so re-export std::slice just for it. |
318 | // | |
319 | // It is also used in vec![] | |
320 | pub use slice; | |
321 | ||
322 | pub use boxed; // used for vec![] | |
1a4d82fc | 323 | } |