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.
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.
11 //! # The Rust Standard Library
13 //! The Rust Standard Library is the foundation of portable Rust software, a
14 //! set of minimal and battle-tested shared abstractions for the [broader Rust
15 //! ecosystem][crates.io]. It offers core types, like [`Vec<T>`] and
16 //! [`Option<T>`], library-defined [operations on language
17 //! primitives](#primitives), [standard macros](#macros), [I/O] and
18 //! [multithreading], among [many other things][other].
20 //! `std` is available to all Rust crates by default, just as if each one
21 //! contained an `extern crate std;` import at the [crate root]. Therefore the
22 //! standard library can be accessed in [`use`] statements through the path
23 //! `std`, as in [`use std::env`], or in expressions through the absolute path
24 //! `::std`, as in [`::std::env::args()`].
26 //! # How to read this documentation
28 //! If you already know the name of what you are looking for, the fastest way to
29 //! find it is to use the <a href="#" onclick="focusSearchBar();">search
30 //! bar</a> at the top of the page.
32 //! Otherwise, you may want to jump to one of these useful sections:
34 //! * [`std::*` modules](#modules)
35 //! * [Primitive types](#primitives)
36 //! * [Standard macros](#macros)
37 //! * [The Rust Prelude](prelude/index.html)
39 //! If this is your first time, the documentation for the standard library is
40 //! written to be casually perused. Clicking on interesting things should
41 //! generally lead you to interesting places. Still, there are important bits
42 //! you don't want to miss, so read on for a tour of the standard library and
43 //! its documentation!
45 //! Once you are familiar with the contents of the standard library you may
46 //! begin to find the verbosity of the prose distracting. At this stage in your
47 //! development you may want to press the **[-]** button near the top of the
48 //! page to collapse it into a more skimmable view.
50 //! While you are looking at that **[-]** button also notice the **[src]**
51 //! button. Rust's API documentation comes with the source code and you are
52 //! encouraged to read it. The standard library source is generally high
53 //! quality and a peek behind the curtains is often enlightening.
55 //! # What is in the standard library documentation?
57 //! First of all, The Rust Standard Library is divided into a number of focused
58 //! modules, [all listed further down this page](#modules). These modules are
59 //! the bedrock upon which all of Rust is forged, and they have mighty names
60 //! like [`std::slice`] and [`std::cmp`]. Modules' documentation typically
61 //! includes an overview of the module along with examples, and are a smart
62 //! place to start familiarizing yourself with the library.
64 //! Second, implicit methods on [primitive types] are documented here. This can
65 //! be a source of confusion for two reasons:
67 //! 1. While primitives are implemented by the compiler, the standard library
68 //! implements methods directly on the primitive types (and it is the only
69 //! library that does so), which are [documented in the section on
70 //! primitives](#primitives).
71 //! 2. The standard library exports many modules *with the same name as
72 //! primitive types*. These define additional items related to the primitive
73 //! type, but not the all-important methods.
75 //! So for example there is a [page for the primitive type
76 //! `i32`](primitive.i32.html) that lists all the methods that can be called on
77 //! 32-bit integers (very useful), and there is a [page for the module
78 //! `std::i32`](i32/index.html) that documents the constant values [`MIN`] and
79 //! [`MAX`](i32/constant.MAX.html) (rarely useful).
81 //! Note the documentation for the primitives [`str`] and [`[T]`][slice] (also
82 //! called 'slice'). Many method calls on [`String`] and [`Vec<T>`] are actually
83 //! calls to methods on [`str`] and [`[T]`][slice] respectively, via [deref
86 //! Third, the standard library defines [The Rust Prelude], a small collection
87 //! of items - mostly traits - that are imported into every module of every
88 //! crate. The traits in the prelude are pervasive, making the prelude
89 //! documentation a good entry point to learning about the library.
91 //! And finally, the standard library exports a number of standard macros, and
92 //! [lists them on this page](#macros) (technically, not all of the standard
93 //! macros are defined by the standard library - some are defined by the
94 //! compiler - but they are documented here the same). Like the prelude, the
95 //! standard macros are imported by default into all crates.
97 //! # A Tour of The Rust Standard Library
99 //! The rest of this crate documentation is dedicated to pointing out notable
100 //! features of The Rust Standard Library.
102 //! ## Containers and collections
104 //! The [`option`] and [`result`] modules define optional and error-handling
105 //! types, [`Option<T>`] and [`Result<T, E>`]. The [`iter`] module defines
106 //! Rust's iterator trait, [`Iterator`], which works with the [`for`] loop to
107 //! access collections.
109 //! The standard library exposes three common ways to deal with contiguous
110 //! regions of memory:
112 //! * [`Vec<T>`] - A heap-allocated *vector* that is resizable at runtime.
113 //! * [`[T; n]`][array] - An inline *array* with a fixed size at compile time.
114 //! * [`[T]`][slice] - A dynamically sized *slice* into any other kind of contiguous
115 //! storage, whether heap-allocated or not.
117 //! Slices can only be handled through some kind of *pointer*, and as such come
118 //! in many flavors such as:
120 //! * `&[T]` - *shared slice*
121 //! * `&mut [T]` - *mutable slice*
122 //! * [`Box<[T]>`][owned slice] - *owned slice*
124 //! [`str`], a UTF-8 string slice, is a primitive type, and the standard library
125 //! defines many methods for it. Rust [`str`]s are typically accessed as
126 //! immutable references: `&str`. Use the owned [`String`] for building and
127 //! mutating strings.
129 //! For converting to strings use the [`format!`] macro, and for converting from
130 //! strings use the [`FromStr`] trait.
132 //! Data may be shared by placing it in a reference-counted box or the [`Rc`]
133 //! type, and if further contained in a [`Cell`] or [`RefCell`], may be mutated
134 //! as well as shared. Likewise, in a concurrent setting it is common to pair an
135 //! atomically-reference-counted box, [`Arc`], with a [`Mutex`] to get the same
138 //! The [`collections`] module defines maps, sets, linked lists and other
139 //! typical collection types, including the common [`HashMap<K, V>`].
141 //! ## Platform abstractions and I/O
143 //! Besides basic data types, the standard library is largely concerned with
144 //! abstracting over differences in common platforms, most notably Windows and
145 //! Unix derivatives.
147 //! Common types of I/O, including [files], [TCP], [UDP], are defined in the
148 //! [`io`], [`fs`], and [`net`] modules.
150 //! The [`thread`] module contains Rust's threading abstractions. [`sync`]
151 //! contains further primitive shared memory types, including [`atomic`] and
152 //! [`mpsc`], which contains the channel types for message passing.
154 //! [I/O]: io/index.html
155 //! [`MIN`]: i32/constant.MIN.html
156 //! [TCP]: net/struct.TcpStream.html
157 //! [The Rust Prelude]: prelude/index.html
158 //! [UDP]: net/struct.UdpSocket.html
159 //! [`::std::env::args()`]: env/fn.args.html
160 //! [`Arc`]: sync/struct.Arc.html
161 //! [owned slice]: boxed/index.html
162 //! [`Cell`]: cell/struct.Cell.html
163 //! [`FromStr`]: str/trait.FromStr.html
164 //! [`HashMap<K, V>`]: collections/struct.HashMap.html
165 //! [`Iterator`]: iter/trait.Iterator.html
166 //! [`Mutex`]: sync/struct.Mutex.html
167 //! [`Option<T>`]: option/enum.Option.html
168 //! [`Rc`]: rc/index.html
169 //! [`RefCell`]: cell/struct.RefCell.html
170 //! [`Result<T, E>`]: result/enum.Result.html
171 //! [`String`]: string/struct.String.html
172 //! [`Vec<T>`]: vec/index.html
173 //! [array]: primitive.array.html
174 //! [slice]: primitive.slice.html
175 //! [`atomic`]: sync/atomic/index.html
176 //! [`collections`]: collections/index.html
177 //! [`for`]: ../book/loops.html#for
178 //! [`format!`]: macro.format!.html
179 //! [`fs`]: fs/index.html
180 //! [`io`]: io/index.html
181 //! [`iter`]: iter/index.html
182 //! [`mpsc`]: sync/mpsc/index.html
183 //! [`net`]: net/index.html
184 //! [`option`]: option/index.html
185 //! [`result`]: result/index.html
186 //! [`std::cmp`]: cmp/index.html
187 //! [`std::slice`]: slice/index.html
188 //! [`str`]: primitive.str.html
189 //! [`sync`]: sync/index.html
190 //! [`thread`]: thread/index.html
191 //! [`use std::env`]: env/index.html
192 //! [`use`]: ../book/crates-and-modules.html#importing-modules-with-use
193 //! [crate root]: ../book/crates-and-modules.html#basic-terminology:-crates-and-modules
194 //! [crates.io]: https://crates.io
195 //! [deref coercions]: ../book/deref-coercions.html
196 //! [files]: fs/struct.File.html
197 //! [multithreading]: thread/index.html
198 //! [other]: #what-is-in-the-standard-library-documentation
199 //! [primitive types]: ../book/primitive-types.html
201 #![crate_name = "std"]
202 #![stable(feature = "rust1", since = "1.0.0")]
203 #![crate_type = "rlib"]
204 #![crate_type = "dylib"]
205 #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
206 html_favicon_url = "https://doc.rust-lang.org/favicon.ico",
207 html_root_url = "https://doc.rust-lang.org/nightly/",
208 html_playground_url = "https://play.rust-lang.org/",
209 issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
210 test(no_crate_inject, attr(deny(warnings))),
211 test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))))]
214 #![feature(allow_internal_unstable)]
216 #![feature(associated_consts)]
217 #![feature(borrow_state)]
218 #![feature(box_syntax)]
219 #![feature(cfg_target_vendor)]
220 #![feature(cfg_target_thread_local)]
221 #![feature(char_internals)]
222 #![feature(collections)]
223 #![feature(collections_bound)]
224 #![feature(const_fn)]
225 #![feature(core_float)]
226 #![feature(core_intrinsics)]
227 #![feature(decode_utf16)]
228 #![feature(drop_in_place)]
229 #![feature(dropck_parametricity)]
230 #![feature(float_extras)]
231 #![feature(float_from_str_radix)]
233 #![feature(heap_api)]
234 #![feature(hashmap_hasher)]
235 #![feature(int_error_internals)]
236 #![feature(into_cow)]
237 #![feature(lang_items)]
239 #![feature(link_args)]
241 #![feature(macro_reexport)]
242 #![feature(num_bits_bytes)]
243 #![feature(old_wrapping)]
244 #![feature(on_unimplemented)]
246 #![feature(optin_builtin_traits)]
247 #![feature(placement_in_syntax)]
249 #![feature(range_inclusive)]
251 #![feature(repr_simd)]
252 #![feature(reflect_marker)]
254 #![feature(slice_bytes)]
255 #![feature(slice_concat_ext)]
256 #![feature(slice_patterns)]
257 #![feature(staged_api)]
258 #![feature(stmt_expr_attributes)]
259 #![feature(str_char)]
260 #![feature(str_internals)]
261 #![feature(str_utf16)]
262 #![feature(test, rustc_private)]
263 #![feature(thread_local)]
264 #![feature(unboxed_closures)]
267 #![feature(unsafe_no_drop_flag, filling_drop)]
268 #![feature(unwind_attributes)]
269 #![feature(vec_push_all)]
270 #![feature(zero_one)]
272 // Issue# 30592: Systematically use alloc_system during stage0 since jemalloc
273 // might be unavailable or disabled
274 #![cfg_attr(stage0, feature(alloc_system))]
276 // Don't link to std. We are std.
279 #![deny(missing_docs)]
280 #![allow(unused_features)] // std may use features in a platform-specific way
281 #![cfg_attr(not(stage0), deny(warnings))]
283 #[cfg(test)] extern crate test;
284 #[cfg(test)] #[macro_use] extern crate log;
286 // We want to reexport a few macros from core but libcore has already been
287 // imported by the compiler (via our #[no_std] attribute) In this case we just
288 // add a new crate name so we can attach the reexports to it.
289 #[macro_reexport(assert, assert_eq, debug_assert, debug_assert_eq,
290 unreachable, unimplemented, write, writeln, try)]
291 extern crate core as __core;
294 #[macro_reexport(vec, format)]
295 extern crate collections as core_collections;
297 #[allow(deprecated)] extern crate rand as core_rand;
299 extern crate rustc_unicode;
303 extern crate alloc_system;
305 // Make std testable by not duplicating lang items and other globals. See #2912
306 #[cfg(test)] extern crate std as realstd;
308 // NB: These reexports are in the order they should be listed in rustdoc
310 #[stable(feature = "rust1", since = "1.0.0")]
312 #[stable(feature = "rust1", since = "1.0.0")]
314 #[stable(feature = "rust1", since = "1.0.0")]
316 #[stable(feature = "rust1", since = "1.0.0")]
318 #[stable(feature = "rust1", since = "1.0.0")]
319 pub use core::convert;
320 #[stable(feature = "rust1", since = "1.0.0")]
321 pub use core::default;
322 #[stable(feature = "rust1", since = "1.0.0")]
324 #[stable(feature = "rust1", since = "1.0.0")]
325 pub use core::intrinsics;
326 #[stable(feature = "rust1", since = "1.0.0")]
328 #[stable(feature = "rust1", since = "1.0.0")]
329 pub use core::marker;
330 #[stable(feature = "rust1", since = "1.0.0")]
332 #[stable(feature = "rust1", since = "1.0.0")]
334 #[stable(feature = "rust1", since = "1.0.0")]
336 #[stable(feature = "rust1", since = "1.0.0")]
338 #[stable(feature = "rust1", since = "1.0.0")]
339 pub use core::result;
340 #[stable(feature = "rust1", since = "1.0.0")]
341 pub use core::option;
345 #[stable(feature = "rust1", since = "1.0.0")]
346 pub use alloc::boxed;
347 #[stable(feature = "rust1", since = "1.0.0")]
350 #[stable(feature = "rust1", since = "1.0.0")]
351 pub use core_collections::borrow;
352 #[stable(feature = "rust1", since = "1.0.0")]
353 pub use core_collections::fmt;
354 #[stable(feature = "rust1", since = "1.0.0")]
355 pub use core_collections::slice;
356 #[stable(feature = "rust1", since = "1.0.0")]
357 pub use core_collections::str;
358 #[stable(feature = "rust1", since = "1.0.0")]
359 pub use core_collections::string;
360 #[stable(feature = "rust1", since = "1.0.0")]
361 pub use core_collections::vec;
363 #[stable(feature = "rust1", since = "1.0.0")]
364 pub use rustc_unicode::char;
366 /* Exported macros */
378 /* Primitive types */
380 // NB: slice and str are primitive types too, but their module docs + primitive
381 // doc pages are inlined from the public re-exports of core_collections::{slice,
384 #[stable(feature = "rust1", since = "1.0.0")]
386 #[stable(feature = "rust1", since = "1.0.0")]
388 #[stable(feature = "rust1", since = "1.0.0")]
390 #[stable(feature = "rust1", since = "1.0.0")]
392 #[stable(feature = "rust1", since = "1.0.0")]
395 #[stable(feature = "rust1", since = "1.0.0")]
397 #[stable(feature = "rust1", since = "1.0.0")]
399 #[stable(feature = "rust1", since = "1.0.0")]
401 #[stable(feature = "rust1", since = "1.0.0")]
403 #[stable(feature = "rust1", since = "1.0.0")]
406 #[path = "num/f32.rs"] pub mod f32;
407 #[path = "num/f64.rs"] pub mod f64;
415 /* Runtime and platform support */
436 #[path = "sys/common/mod.rs"] mod sys_common;
439 #[path = "sys/unix/mod.rs"] mod sys;
441 #[path = "sys/windows/mod.rs"] mod sys;
447 // Some external utilities of the standard library rely on randomness (aka
448 // rustc_back::TempDir and tests) and need a way to get at the OS rng we've got
449 // here. This module is not at all intended for stabilization as-is, however,
450 // but it may be stabilized long-term. As a result we're exposing a hidden,
451 // unstable module so we can get our build working.
453 #[unstable(feature = "rand", issue = "0")]
455 pub use rand::{thread_rng, ThreadRng, Rng};
458 // Include a number of private modules that exist solely to provide
459 // the rustdoc documentation for primitive types. Using `include!`
460 // because rustdoc only looks for these modules at the crate level.
461 include!("primitive_docs.rs");