diff options
| -rw-r--r-- | src/libstd/lib.rs | 274 |
1 files changed, 144 insertions, 130 deletions
diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 93d1ce168b7..aec84da3048 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -10,32 +10,24 @@ //! # The Rust Standard Library //! -//! The Rust Standard Library is the foundation of portable Rust -//! software, a set of minimal and battle-tested shared abstractions -//! for the [broader Rust ecosystem](https://crates.io). It offers -//! core types, like [`Vec`](vec/index.html) -//! and [`Option`](option/index.html), library-defined [operations on -//! language primitives](#primitives), [standard macros](#macros), -//! [I/O](io/index.html) and [multithreading](thread/index.html), among -//! [many other -//! things](#what-is-in-the-standard-library-documentation). -//! -//! `std` is available to all Rust crates by default, just as if each -//! one contained an `extern crate std` import at the [crate -//! root][book-crate-root]. Therefore the standard library can be -//! accessed in [`use`][book-use] statements through the path `std`, -//! as in [`use std::env`](env/index.html), or in expressions -//! through the absolute path `::std`, as in -//! [`::std::env::args()`](env/fn.args.html). -//! -//! [book-crate-root]: ../book/crates-and-modules.html#basic-terminology:-crates-and-modules -//! [book-use]: ../book/crates-and-modules.html#importing-modules-with-use +//! The Rust Standard Library is the foundation of portable Rust software, a +//! set of minimal and battle-tested shared abstractions for the [broader Rust +//! ecosystem][crates.io]. It offers core types, like [`Vec<T>`] and +//! [`Option<T>`], library-defined [operations on language +//! primitives](#primitives), [standard macros](#macros), [I/O] and +//! [multithreading], among [many other things][other]. +//! +//! `std` is available to all Rust crates by default, just as if each one +//! contained an `extern crate std;` import at the [crate root]. Therefore the +//! standard library can be accessed in [`use`] statements through the path +//! `std`, as in [`use std::env`], or in expressions through the absolute path +//! `::std`, as in [`::std::env::args()`]. //! //! # How to read this documentation //! -//! If you already know the name of what you are looking for the -//! fastest way to find it is to use the <a href="#" -//! onclick="focusSearchBar();">search bar</a> at the top of the page. +//! If you already know the name of what you are looking for the fastest way to +//! find it is to use the <a href="#" onclick="focusSearchBar();">search +//! bar</a> at the top of the page. //! //! Otherwise, you may want to jump to one of these useful sections: //! @@ -44,145 +36,167 @@ //! * [Standard macros](#macros) //! * [The Rust Prelude](prelude/index.html) //! -//! If this is your first time, the documentation for the standard -//! library is written to be casually perused. Clicking on interesting -//! things should generally lead you to interesting places. Still, -//! there are important bits you don't want to miss, so read on for a -//! tour of the standard library and its documentation! +//! If this is your first time, the documentation for the standard library is +//! written to be casually perused. Clicking on interesting things should +//! generally lead you to interesting places. Still, there are important bits +//! you don't want to miss, so read on for a tour of the standard library and +//! its documentation! //! -//! Once you are familiar with the contents of the standard library -//! you may begin to find the verbosity of the prose distracting. At -//! this stage in your development you may want to press the **[-]** -//! button near the top of the page to collapse it into a more -//! skimmable view. +//! Once you are familiar with the contents of the standard library you may +//! begin to find the verbosity of the prose distracting. At this stage in your +//! development you may want to press the **[-]** button near the top of the +//! page to collapse it into a more skimmable view. //! -//! While you are looking at that **[-]** button also notice the -//! **[src]** button. Rust's API documentation comes with the source -//! code and you are encouraged to read it. The standard library -//! source is generally high quality and a peek behind the curtains is -//! often enlightening. +//! While you are looking at that **[-]** button also notice the **[src]** +//! button. Rust's API documentation comes with the source code and you are +//! encouraged to read it. The standard library source is generally high +//! quality and a peek behind the curtains is often enlightening. //! //! # What is in the standard library documentation? //! -//! First of all, The Rust Standard Library is divided into a number -//! of focused modules, [all listed further down this page](#modules). -//! These modules are the bedrock upon which all of Rust is forged, -//! and they have mighty names like [`std::slice`](slice/index.html) -//! and [`std::cmp`](cmp/index.html). Modules' documentation typically -//! includes an overview of the module along with examples, and are -//! a smart place to start familiarizing yourself with the library. +//! First of all, The Rust Standard Library is divided into a number of focused +//! modules, [all listed further down this page](#modules). These modules are +//! the bedrock upon which all of Rust is forged, and they have mighty names +//! like [`std::slice`] and [`std::cmp`]. Modules' documentation typically +//! includes an overview of the module along with examples, and are a smart +//! place to start familiarizing yourself with the library. //! -//! Second, implicit methods on [primitive -//! types](../book/primitive-types.html) are documented here. This can +//! Second, implicit methods on [primitive types] are documented here. This can //! be a source of confusion for two reasons: //! -//! 1. While primitives are implemented by the compiler, the standard -//! library implements methods directly on the primitive types (and -//! it is the only library that does so), which are [documented in -//! the section on primitives](#primitives). -//! 2. The standard library exports many modules *with the same name -//! as primitive types*. These define additional items related -//! to the primitive type, but not the all-important methods. +//! 1. While primitives are implemented by the compiler, the standard library +//! implements methods directly on the primitive types (and it is the only +//! library that does so), which are [documented in the section on +//! primitives](#primitives). +//! 2. The standard library exports many modules *with the same name as +//! primitive types*. These define additional items related to the primitive +//! type, but not the all-important methods. //! //! So for example there is a [page for the primitive type -//! `i32`](primitive.i32.html) that lists all the methods that can be -//! called on 32-bit integers (very useful), and there is a [page for -//! the module `std::i32`](i32/index.html) that documents the constant -//! values `MIN` and `MAX` (rarely useful). -//! -//! Note the documentation for the primitives -//! [`str`](primitive.str.html) and [`[T]`](primitive.slice.html) -//! (also called 'slice'). Many method calls on -//! [`String`](string/struct.String.html) and -//! [`Vec`](vec/struct.Vec.html) are actually calls to methods on -//! `str` and `[T]` respectively, via [deref -//! coercions](../book/deref-coercions.html). -//! -//! Third, the standard library defines [The Rust -//! Prelude](prelude/index.html), a small collection of items - mostly -//! traits - that are imported into every module of every crate. The -//! traits in the prelude are pervasive, making the prelude +//! `i32`](primitive.i32.html) that lists all the methods that can be called on +//! 32-bit integers (very useful), and there is a [page for the module +//! `std::i32`](i32/index.html) that documents the constant values [`MIN`] and +//! [`MAX`] (rarely useful). +//! +//! Note the documentation for the primitives [`str`] and [`[T]`] (also called +//! 'slice'). Many method calls on [`String`] and [`Vec<T>`] are actually calls +//! to methods on [`str`] and [`[T]`] respectively, via [deref coercions]. +//! +//! Third, the standard library defines [The Rust Prelude], a small collection +//! of items - mostly traits - that are imported into every module of every +//! crate. The traits in the prelude are pervasive, making the prelude //! documentation a good entry point to learning about the library. //! -//! And finally, the standard library exports a number of standard -//! macros, and [lists them on this page](#macros) (technically, not -//! all of the standard macros are defined by the standard library - -//! some are defined by the compiler - but they are documented here -//! the same). Like the prelude, the standard macros are imported by -//! default into all crates. +//! And finally, the standard library exports a number of standard macros, and +//! [lists them on this page](#macros) (technically, not all of the standard +//! macros are defined by the standard library - some are defined by the +//! compiler - but they are documented here the same). Like the prelude, the +//! standard macros are imported by default into all crates. //! //! # A Tour of The Rust Standard Library //! -//! The rest of this crate documentation is dedicated to pointing -//! out notable features of The Rust Standard Library. +//! The rest of this crate documentation is dedicated to pointing out notable +//! features of The Rust Standard Library. //! //! ## Containers and collections //! -//! The [`option`](option/index.html) and -//! [`result`](result/index.html) modules define optional and -//! error-handling types, `Option` and `Result`. The -//! [`iter`](iter/index.html) module defines Rust's iterator trait, -//! [`Iterator`](iter/trait.Iterator.html), which works with the `for` -//! loop to access collections. +//! The [`option`] and [`result`] modules define optional and error-handling +//! types, [`Option<T>`] and [`Result<T, E>`]. The [`iter`] module defines +//! Rust's iterator trait, [`Iterator`], which works with the [`for`] loop to +//! access collections. //! -//! The standard library exposes 3 common ways to deal with contiguous +//! The standard library exposes three common ways to deal with contiguous //! regions of memory: //! -//! * [`Vec<T>`](vec/index.html) - A heap-allocated *vector* that is -//! resizable at runtime. -//! * [`[T; n]`](primitive.array.html) - An inline *array* with a -//! fixed size at compile time. -//! * [`[T]`](primitive.slice.html) - A dynamically sized *slice* into -//! any other kind of contiguous storage, whether heap-allocated or -//! not. +//! * [`Vec<T>`] - A heap-allocated *vector* that is resizable at runtime. +//! * [`[T; n]`] - An inline *array* with a fixed size at compile time. +//! * [`[T]`] - A dynamically sized *slice* into any other kind of contiguous +//! storage, whether heap-allocated or not. //! -//! Slices can only be handled through some kind of *pointer*, and as -//! such come in many flavors such as: +//! Slices can only be handled through some kind of *pointer*, and as such come +//! in many flavors such as: //! //! * `&[T]` - *shared slice* //! * `&mut [T]` - *mutable slice* -//! * [`Box<[T]>`](boxed/index.html) - *owned slice* +//! * [`Box<[T]>`] - *owned slice* //! -//! `str`, a UTF-8 string slice, is a primitive type, and the standard -//! library defines [many methods for it](primitive.str.html). Rust -//! `str`s are typically accessed as immutable references: `&str`. Use -//! the owned `String` type defined in [`string`](string/index.html) -//! for building and mutating strings. +//! [`str`], a UTF-8 string slice, is a primitive type, and the standard library +//! defines many methods for it. Rust [`str`]s are typically accessed as +//! immutable references: `&str`. Use the owned [`String`] for building and +//! mutating strings. //! -//! For converting to strings use the [`format!`](fmt/index.html) -//! macro, and for converting from strings use the -//! [`FromStr`](str/trait.FromStr.html) trait. +//! For converting to strings use the [`format!`] macro, and for converting from +//! strings use the [`FromStr`] trait. //! -//! Data may be shared by placing it in a reference-counted box or the -//! [`Rc`](rc/index.html) type, and if further contained in a [`Cell` -//! or `RefCell`](cell/index.html), may be mutated as well as shared. -//! Likewise, in a concurrent setting it is common to pair an -//! atomically-reference-counted box, [`Arc`](sync/struct.Arc.html), -//! with a [`Mutex`](sync/struct.Mutex.html) to get the same effect. +//! Data may be shared by placing it in a reference-counted box or the [`Rc`] +//! type, and if further contained in a [`Cell`] or [`RefCell`], may be mutated +//! as well as shared. Likewise, in a concurrent setting it is common to pair an +//! atomically-reference-counted box, [`Arc`], with a [`Mutex`] to get the same +//! effect. //! -//! The [`collections`](collections/index.html) module defines maps, -//! sets, linked lists and other typical collection types, including -//! the common [`HashMap`](collections/struct.HashMap.html). +//! The [`collections`] module defines maps, sets, linked lists and other +//! typical collection types, including the common [`HashMap<K, V>`]. //! //! ## Platform abstractions and I/O //! -//! Besides basic data types, the standard library is largely concerned -//! with abstracting over differences in common platforms, most notably -//! Windows and Unix derivatives. -//! -//! Common types of I/O, including [files](fs/struct.File.html), -//! [TCP](net/struct.TcpStream.html), -//! [UDP](net/struct.UdpSocket.html), are defined in the -//! [`io`](io/index.html), [`fs`](fs/index.html), and -//! [`net`](net/index.html) modules. -//! -//! The [`thread`](thread/index.html) module contains Rust's threading -//! abstractions. [`sync`](sync/index.html) contains further -//! primitive shared memory types, including -//! [`atomic`](sync/atomic/index.html) and -//! [`mpsc`](sync/mpsc/index.html), which contains the channel types -//! for message passing. -//! +//! Besides basic data types, the standard library is largely concerned with +//! abstracting over differences in common platforms, most notably Windows and +//! Unix derivatives. +//! +//! Common types of I/O, including [files], [TCP], [UDP], are defined in the +//! [`io`], [`fs`], and [`net`] modules. +//! +//! The [`thread`] module contains Rust's threading abstractions. [`sync`] +//! contains further primitive shared memory types, including [`atomic`] and +//! [`mpsc`], which contains the channel types for message passing. +//! +//! [I/O]: io/index.html +//! [MIN]: i32/constant.MIN.html +//! [MAX]: i32/constant.MAX.html +//! [TCP]: net/struct.TcpStream.html +//! [The Rust Prelude]: prelude/index.html +//! [UDP]: net/struct.UdpSocket.html +//! [`::std::env::args()`]: env/fn.args.html +//! [`Arc`]: sync/struct.Arc.html +//! [`Box<[T]>`]: boxed/index.html +//! [`Cell`]: cell/struct.Cell.html +//! [`FromStr`]: str/trait.FromStr.html +//! [`HashMap<K, V>`]: collections/struct.HashMap.html +//! [`Iterator`]: iter/trait.Iterator.html +//! [`Mutex`]: sync/struct.Mutex.html +//! [`Option<T>`]: option/enum.Option.html +//! [`Rc`]: rc/index.html +//! [`RefCell`]: cell/struct.RefCell.html +//! [`Result<T, E>`]: result/enum.Result.html +//! [`String`]: string/struct.String.html +//! [`Vec<T>`]: vec/index.html +//! [`[T; n]`]: primitive.array.html +//! [`[T]`]: primitive.slice.html +//! [`atomic`]: sync/atomic/index.html +//! [`collections`]: collections/index.html +//! [`for`]: ../book/loops.html#for +//! [`format!`]: macro.format!.html +//! [`fs`]: fs/index.html +//! [`io`]: io/index.html +//! [`iter`]: iter/index.html +//! [`mpsc`]: sync/mpsc/index.html +//! [`net`]: net/index.html +//! [`option`]: option/index.html +//! [`result`]: result/index.html +//! [`std::cmp`]: cmp/index.html +//! [`std::slice`]: slice/index.html +//! [`str`]: primitive.str.html +//! [`sync`]: sync/index.html +//! [`thread`]: thread/index.html +//! [`use std::env`]: env/index.html +//! [`use`]: ../book/crates-and-modules.html#importing-modules-with-use +//! [crate root]: ../book/crates-and-modules.html#basic-terminology:-crates-and-modules +//! [crates.io]: https://crates.io +//! [deref coercions]: ../book/deref-coercions.html +//! [files]: fs/struct.File.html +//! [multithreading]: thread/index.html +//! [other]: #what-is-in-the-standard-library-documentation +//! [primitive types]: ../book/primitive-types.html // Do not remove on snapshot creation. Needed for bootstrap. (Issue #22364) #![cfg_attr(stage0, feature(custom_attribute))] |