]> git.proxmox.com Git - rustc.git/blob - src/libstd/lib.rs
Imported Upstream version 1.9.0+dfsg1
[rustc.git] / src / libstd / lib.rs
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 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].
19 //!
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()`].
25 //!
26 //! # How to read this documentation
27 //!
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.
31 //!
32 //! Otherwise, you may want to jump to one of these useful sections:
33 //!
34 //! * [`std::*` modules](#modules)
35 //! * [Primitive types](#primitives)
36 //! * [Standard macros](#macros)
37 //! * [The Rust Prelude](prelude/index.html)
38 //!
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!
44 //!
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.
49 //!
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.
54 //!
55 //! # What is in the standard library documentation?
56 //!
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.
63 //!
64 //! Second, implicit methods on [primitive types] are documented here. This can
65 //! be a source of confusion for two reasons:
66 //!
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.
74 //!
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).
80 //!
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
84 //! coercions].
85 //!
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.
90 //!
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.
96 //!
97 //! # A Tour of The Rust Standard Library
98 //!
99 //! The rest of this crate documentation is dedicated to pointing out notable
100 //! features of The Rust Standard Library.
101 //!
102 //! ## Containers and collections
103 //!
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.
108 //!
109 //! The standard library exposes three common ways to deal with contiguous
110 //! regions of memory:
111 //!
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.
116 //!
117 //! Slices can only be handled through some kind of *pointer*, and as such come
118 //! in many flavors such as:
119 //!
120 //! * `&[T]` - *shared slice*
121 //! * `&mut [T]` - *mutable slice*
122 //! * [`Box<[T]>`][owned slice] - *owned slice*
123 //!
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.
128 //!
129 //! For converting to strings use the [`format!`] macro, and for converting from
130 //! strings use the [`FromStr`] trait.
131 //!
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
136 //! effect.
137 //!
138 //! The [`collections`] module defines maps, sets, linked lists and other
139 //! typical collection types, including the common [`HashMap<K, V>`].
140 //!
141 //! ## Platform abstractions and I/O
142 //!
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.
146 //!
147 //! Common types of I/O, including [files], [TCP], [UDP], are defined in the
148 //! [`io`], [`fs`], and [`net`] modules.
149 //!
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.
153 //!
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
200
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))))]
212
213 #![feature(alloc)]
214 #![feature(allow_internal_unstable)]
215 #![feature(asm)]
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(dropck_parametricity)]
228 #![feature(float_extras)]
229 #![feature(float_from_str_radix)]
230 #![feature(fnbox)]
231 #![feature(fn_traits)]
232 #![feature(heap_api)]
233 #![feature(hashmap_hasher)]
234 #![feature(inclusive_range)]
235 #![feature(int_error_internals)]
236 #![feature(into_cow)]
237 #![feature(lang_items)]
238 #![feature(libc)]
239 #![feature(link_args)]
240 #![feature(linkage)]
241 #![feature(macro_reexport)]
242 #![cfg_attr(test, feature(map_values_mut))]
243 #![feature(num_bits_bytes)]
244 #![feature(old_wrapping)]
245 #![feature(on_unimplemented)]
246 #![feature(oom)]
247 #![feature(optin_builtin_traits)]
248 #![feature(placement_in_syntax)]
249 #![feature(rand)]
250 #![feature(raw)]
251 #![feature(repr_simd)]
252 #![feature(reflect_marker)]
253 #![feature(rustc_attrs)]
254 #![feature(shared)]
255 #![feature(slice_bytes)]
256 #![feature(slice_concat_ext)]
257 #![feature(slice_patterns)]
258 #![feature(staged_api)]
259 #![feature(stmt_expr_attributes)]
260 #![feature(str_char)]
261 #![feature(str_internals)]
262 #![feature(str_utf16)]
263 #![feature(test, rustc_private)]
264 #![feature(thread_local)]
265 #![feature(unboxed_closures)]
266 #![feature(unicode)]
267 #![feature(unique)]
268 #![feature(unsafe_no_drop_flag, filling_drop)]
269 #![feature(unwind_attributes)]
270 #![feature(vec_push_all)]
271 #![feature(zero_one)]
272 #![feature(question_mark)]
273
274 // Issue# 30592: Systematically use alloc_system during stage0 since jemalloc
275 // might be unavailable or disabled
276 #![cfg_attr(stage0, feature(alloc_system))]
277
278 // Don't link to std. We are std.
279 #![no_std]
280
281 #![deny(missing_docs)]
282 #![allow(unused_features)] // std may use features in a platform-specific way
283 #![cfg_attr(not(stage0), deny(warnings))]
284
285 #[cfg(test)] extern crate test;
286
287 // We want to reexport a few macros from core but libcore has already been
288 // imported by the compiler (via our #[no_std] attribute) In this case we just
289 // add a new crate name so we can attach the reexports to it.
290 #[macro_reexport(assert, assert_eq, debug_assert, debug_assert_eq,
291 unreachable, unimplemented, write, writeln, try)]
292 extern crate core as __core;
293
294 #[macro_use]
295 #[macro_reexport(vec, format)]
296 extern crate collections as core_collections;
297
298 #[allow(deprecated)] extern crate rand as core_rand;
299 extern crate alloc;
300 extern crate rustc_unicode;
301 extern crate libc;
302
303 #[cfg(stage0)]
304 extern crate alloc_system;
305
306 // Make std testable by not duplicating lang items and other globals. See #2912
307 #[cfg(test)] extern crate std as realstd;
308
309 // NB: These reexports are in the order they should be listed in rustdoc
310
311 #[stable(feature = "rust1", since = "1.0.0")]
312 pub use core::any;
313 #[stable(feature = "rust1", since = "1.0.0")]
314 pub use core::cell;
315 #[stable(feature = "rust1", since = "1.0.0")]
316 pub use core::clone;
317 #[stable(feature = "rust1", since = "1.0.0")]
318 pub use core::cmp;
319 #[stable(feature = "rust1", since = "1.0.0")]
320 pub use core::convert;
321 #[stable(feature = "rust1", since = "1.0.0")]
322 pub use core::default;
323 #[stable(feature = "rust1", since = "1.0.0")]
324 pub use core::hash;
325 #[stable(feature = "rust1", since = "1.0.0")]
326 pub use core::intrinsics;
327 #[stable(feature = "rust1", since = "1.0.0")]
328 pub use core::iter;
329 #[stable(feature = "rust1", since = "1.0.0")]
330 pub use core::marker;
331 #[stable(feature = "rust1", since = "1.0.0")]
332 pub use core::mem;
333 #[stable(feature = "rust1", since = "1.0.0")]
334 pub use core::ops;
335 #[stable(feature = "rust1", since = "1.0.0")]
336 pub use core::ptr;
337 #[stable(feature = "rust1", since = "1.0.0")]
338 pub use core::raw;
339 #[stable(feature = "rust1", since = "1.0.0")]
340 pub use core::result;
341 #[stable(feature = "rust1", since = "1.0.0")]
342 pub use core::option;
343
344 pub mod error;
345
346 #[stable(feature = "rust1", since = "1.0.0")]
347 pub use alloc::boxed;
348 #[stable(feature = "rust1", since = "1.0.0")]
349 pub use alloc::rc;
350
351 #[stable(feature = "rust1", since = "1.0.0")]
352 pub use core_collections::borrow;
353 #[stable(feature = "rust1", since = "1.0.0")]
354 pub use core_collections::fmt;
355 #[stable(feature = "rust1", since = "1.0.0")]
356 pub use core_collections::slice;
357 #[stable(feature = "rust1", since = "1.0.0")]
358 pub use core_collections::str;
359 #[stable(feature = "rust1", since = "1.0.0")]
360 pub use core_collections::string;
361 #[stable(feature = "rust1", since = "1.0.0")]
362 pub use core_collections::vec;
363
364 #[stable(feature = "rust1", since = "1.0.0")]
365 pub use rustc_unicode::char;
366
367 /* Exported macros */
368
369 #[macro_use]
370 mod macros;
371
372 mod rtdeps;
373
374 /* The Prelude. */
375
376 pub mod prelude;
377
378
379 /* Primitive types */
380
381 // NB: slice and str are primitive types too, but their module docs + primitive
382 // doc pages are inlined from the public re-exports of core_collections::{slice,
383 // str} above.
384
385 #[stable(feature = "rust1", since = "1.0.0")]
386 pub use core::isize;
387 #[stable(feature = "rust1", since = "1.0.0")]
388 pub use core::i8;
389 #[stable(feature = "rust1", since = "1.0.0")]
390 pub use core::i16;
391 #[stable(feature = "rust1", since = "1.0.0")]
392 pub use core::i32;
393 #[stable(feature = "rust1", since = "1.0.0")]
394 pub use core::i64;
395
396 #[stable(feature = "rust1", since = "1.0.0")]
397 pub use core::usize;
398 #[stable(feature = "rust1", since = "1.0.0")]
399 pub use core::u8;
400 #[stable(feature = "rust1", since = "1.0.0")]
401 pub use core::u16;
402 #[stable(feature = "rust1", since = "1.0.0")]
403 pub use core::u32;
404 #[stable(feature = "rust1", since = "1.0.0")]
405 pub use core::u64;
406
407 #[path = "num/f32.rs"] pub mod f32;
408 #[path = "num/f64.rs"] pub mod f64;
409
410 pub mod ascii;
411
412 /* Common traits */
413
414 pub mod num;
415
416 /* Runtime and platform support */
417
418 #[macro_use]
419 pub mod thread;
420
421 pub mod collections;
422 pub mod env;
423 pub mod ffi;
424 pub mod fs;
425 pub mod io;
426 pub mod net;
427 pub mod os;
428 pub mod panic;
429 pub mod path;
430 pub mod process;
431 pub mod sync;
432 pub mod time;
433 mod memchr;
434
435 #[macro_use]
436 #[path = "sys/common/mod.rs"] mod sys_common;
437
438 #[cfg(unix)]
439 #[path = "sys/unix/mod.rs"] mod sys;
440 #[cfg(windows)]
441 #[path = "sys/windows/mod.rs"] mod sys;
442
443 pub mod rt;
444 mod panicking;
445 mod rand;
446
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.
452 #[doc(hidden)]
453 #[unstable(feature = "rand", issue = "0")]
454 pub mod __rand {
455 pub use rand::{thread_rng, ThreadRng, Rng};
456 }
457
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");