Rollup merge of #26977 - brson:stddoc, r=Gankro
Yet another attempt to make the prose on the std crate page clearer and more informative. This does a lot of things: tightens up the opening, adds useful links (including a link to the search bar), offers guidance on how to use the docs, and expands the prelude docs as a useful newbie entrypoint. r? @steveklabnik cc @aturon
This commit is contained in:
Manish Goregaokar
commit
3a5bc736ae
3 changed files with 229 additions and 35 deletions
|
|
@ -951,3 +951,8 @@
|
|||
}());
|
||||
|
||||
}());
|
||||
|
||||
// Sets the focus on the search bar at the top of the page
|
||||
function focusSearchBar() {
|
||||
document.getElementsByName('search')[0].focus();
|
||||
}
|
||||
|
|
|
|||
|
|
@ -10,29 +10,116 @@
|
|||
|
||||
//! # The Rust Standard Library
|
||||
//!
|
||||
//! The Rust Standard Library provides the essential runtime
|
||||
//! functionality for building portable Rust software.
|
||||
//! 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 (e.g. [`Vec`](vec/index.html)
|
||||
//! and [`Option`](option/index.html)), library-defined [operations on
|
||||
//! language primitives](#primitive) (e.g. [`u32`](u32/index.html) and
|
||||
//! [`str`](str/index.html)), [standard macros](#macros),
|
||||
//! [I/O](io/index.html) and [multithreading](thread/index.html), among
|
||||
//! [many other lovely
|
||||
//! things](#what-is-in-the-standard-library-documentation?).
|
||||
//!
|
||||
//! The Rust Standard Library is available to all Rust crates by
|
||||
//! default, just as if 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::thread`,
|
||||
//! or in expressions through the absolute path `::std`, as in
|
||||
//! `::std::thread::sleep_ms(100)`.
|
||||
//! `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).
|
||||
//!
|
||||
//! Furthermore, the standard library defines [The Rust
|
||||
//! Prelude](prelude/index.html), a small collection of items, mostly
|
||||
//! traits, that are imported into and available in every module.
|
||||
//! [book-crate-root]: ../book/crates-and-modules.html#basic-terminology:-crates-and-modules
|
||||
//! [book-use]: ../book/crates-and-modules.html#importing-modules-with-use
|
||||
//!
|
||||
//! ## What is in the standard library
|
||||
//! # How to read this documentation
|
||||
//!
|
||||
//! The standard library is a set of minimal, battle-tested
|
||||
//! core types and shared abstractions for the [broader Rust
|
||||
//! ecosystem](https://crates.io) to build on.
|
||||
//! 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.
|
||||
//!
|
||||
//! The [primitive types](#primitives), though not defined in the
|
||||
//! standard library, are documented here, as are the predefined
|
||||
//! [macros](#macros).
|
||||
//! Otherwise, you may want to jump to one of these useful sections:
|
||||
//!
|
||||
//! * [`std::*` modules](#modules)
|
||||
//! * [Primitive types](#primitives)
|
||||
//! * [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!
|
||||
//!
|
||||
//! 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.
|
||||
//!
|
||||
//! # What is in the standard library documentation?
|
||||
//!
|
||||
//! Lots of stuff. Well, broadly four things actually.
|
||||
//!
|
||||
//! 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.
|
||||
//!
|
||||
//! Second, implicit methods on [primitive
|
||||
//! types](../book/primitive-types.html) 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.
|
||||
//!
|
||||
//! 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 (mega 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). *Accepting that
|
||||
//! primitive types are documented on their own pages will bring you a
|
||||
//! deep inner wisdom. Embrace it now before proceeding.*
|
||||
//!
|
||||
//! 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
|
||||
//! 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.
|
||||
//!
|
||||
//! # 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.
|
||||
//!
|
||||
//! ## Containers and collections
|
||||
//!
|
||||
|
|
@ -43,17 +130,29 @@
|
|||
//! [`Iterator`](iter/trait.Iterator.html), which works with the `for`
|
||||
//! loop to access collections.
|
||||
//!
|
||||
//! The common container type, `Vec`, a growable vector backed by an array,
|
||||
//! lives in the [`vec`](vec/index.html) module. Contiguous, unsized regions
|
||||
//! of memory, `[T]`, commonly called "slices", and their borrowed versions,
|
||||
//! `&[T]`, commonly called "borrowed slices", are built-in types for which the
|
||||
//! [`slice`](slice/index.html) module defines many methods.
|
||||
//! The standard library exposes 3 common ways to deal with contiguous
|
||||
//! regions of memory:
|
||||
//!
|
||||
//! `&str`, a UTF-8 string, is a built-in type, and the standard library
|
||||
//! defines methods for it on a variety of traits in the
|
||||
//! [`str`](str/index.html) module. Rust strings are immutable;
|
||||
//! use the `String` type defined in [`string`](string/index.html)
|
||||
//! for a mutable string builder.
|
||||
//! * [`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.
|
||||
//!
|
||||
//! Slices can only be handled through some kind of *pointer*, and as
|
||||
//! such come in many flavours such as:
|
||||
//!
|
||||
//! * `&[T]` - *shared slice*
|
||||
//! * `&mut [T]` - *mutable slice*
|
||||
//! * [`Box<[T]>`](boxed/index.html) - *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.
|
||||
//!
|
||||
//! For converting to strings use the [`format!`](fmt/index.html)
|
||||
//! macro, and for converting from strings use the
|
||||
|
|
@ -88,6 +187,7 @@
|
|||
//! [`atomic`](sync/atomic/index.html) and
|
||||
//! [`mpsc`](sync/mpsc/index.html), which contains the channel types
|
||||
//! for message passing.
|
||||
//!
|
||||
|
||||
// Do not remove on snapshot creation. Needed for bootstrap. (Issue #22364)
|
||||
#![cfg_attr(stage0, feature(custom_attribute))]
|
||||
|
|
|
|||
|
|
@ -22,18 +22,107 @@
|
|||
//! with the `std::` path prefix, as in `use std::vec`, `use std::thread::spawn`,
|
||||
//! etc.
|
||||
//!
|
||||
//! Additionally, `std` contains a `prelude` module that reexports many of the
|
||||
//! most common traits, types and functions. The contents of the prelude are
|
||||
//! imported into every *module* by default. Implicitly, all modules behave as if
|
||||
//! they contained the following prologue:
|
||||
//! Additionally, `std` contains a versioned *prelude* that reexports many of the
|
||||
//! most common traits, types and functions. *The contents of the prelude are
|
||||
//! imported into every module by default*. Implicitly, all modules behave as if
|
||||
//! they contained the following [`use` statement][book-use]:
|
||||
//!
|
||||
//! [book-use]: ../../book/crates-and-modules.html#importing-modules-with-use
|
||||
//!
|
||||
//! ```ignore
|
||||
//! use std::prelude::v1::*;
|
||||
//! ```
|
||||
//!
|
||||
//! The prelude is primarily concerned with exporting *traits* that are so
|
||||
//! pervasive that it would be obnoxious to import for every use, particularly
|
||||
//! those that define methods on primitive types.
|
||||
//! The prelude is primarily concerned with exporting *traits* that
|
||||
//! are so pervasive that they would be onerous to import for every use,
|
||||
//! particularly those that are commonly mentioned in [generic type
|
||||
//! bounds][book-traits].
|
||||
//!
|
||||
//! The current version of the prelude (version 1) lives in
|
||||
//! [`std::prelude::v1`](v1/index.html), and reexports the following.
|
||||
//!
|
||||
//! * `std::marker::`{
|
||||
//! [`Copy`](../marker/trait.Copy.html),
|
||||
//! [`Send`](../marker/trait.Send.html),
|
||||
//! [`Sized`](../marker/trait.Sized.html),
|
||||
//! [`Sync`](../marker/trait.Sync.html)
|
||||
//! }.
|
||||
//! The marker traits indicate fundamental properties of types.
|
||||
//! * `std::ops::`{
|
||||
//! [`Drop`](../ops/trait.Drop.html),
|
||||
//! [`Fn`](../ops/trait.Fn.html),
|
||||
//! [`FnMut`](../ops/trait.FnMut.html),
|
||||
//! [`FnOnce`](../ops/trait.FnOnce.html)
|
||||
//! }.
|
||||
//! The [destructor][book-dtor] trait and the
|
||||
//! [closure][book-closures] traits, reexported from the same
|
||||
//! [module that also defines overloaded
|
||||
//! operators](../ops/index.html).
|
||||
//! * `std::mem::`[`drop`](../mem/fn.drop.html).
|
||||
//! A convenience function for explicitly dropping a value.
|
||||
//! * `std::boxed::`[`Box`](../boxed/struct.Box.html).
|
||||
//! The owned heap pointer.
|
||||
//! * `std::borrow::`[`ToOwned`](../borrow/trait.ToOwned.html).
|
||||
//! The conversion trait that defines `to_owned`, the generic method
|
||||
//! for creating an owned type from a borrowed type.
|
||||
//! * `std::clone::`[`Clone`](../clone/trait.Clone.html).
|
||||
//! The ubiquitous trait that defines `clone`, the method for
|
||||
//! producing copies of values that are consider expensive to copy.
|
||||
//! * `std::cmp::`{
|
||||
//! [`PartialEq`](../cmp/trait.PartialEq.html),
|
||||
//! [`PartialOrd`](../cmp/trait.PartialOrd.html),
|
||||
//! [`Eq`](../cmp/trait.Eq.html),
|
||||
//! [`Ord`](../cmp/trait.Ord.html)
|
||||
//! }.
|
||||
//! The comparision traits, which implement the comparison operators
|
||||
//! and are often seen in trait bounds.
|
||||
//! * `std::convert::`{
|
||||
//! [`AsRef`](../convert/trait.AsRef.html),
|
||||
//! [`AsMut`](../convert/trait.AsMut.html),
|
||||
//! [`Into`](../convert/trait.Into.html),
|
||||
//! [`From`](../convert/trait.From.html)
|
||||
//! }.
|
||||
//! Generic conversions, used by savvy API authors to create
|
||||
//! overloaded methods.
|
||||
//! * `std::default::`[`Default`](../default/trait.Default).
|
||||
//! Types that have default values.
|
||||
//! * `std::iter::`{
|
||||
//! [`Iterator`](../iter/trait.Iterator.html),
|
||||
//! [`Extend`](../iter/trait.Extend.html),
|
||||
//! [`IntoIterator`](../iter/trait.IntoIterator.html),
|
||||
//! [`DoubleEndedIterator`](../iter/trait.DoubleEndedIterator.html),
|
||||
//! [`ExactSizeIterator`](../iter/trait.ExactSizeIterator.html)
|
||||
//! }.
|
||||
//! [Iterators][book-iter].
|
||||
//! * `std::option::Option::`{
|
||||
//! [`self`](../option/enum.Option.html),
|
||||
//! [`Some`](../option/enum.Option.html),
|
||||
//! [`None`](../option/enum.Option.html)
|
||||
//! }.
|
||||
//! The ubiquitous `Option` type and its two [variants][book-enums],
|
||||
//! `Some` and `None`.
|
||||
//! * `std::result::Result::`{
|
||||
//! [`self`](../result/enum.Result.html),
|
||||
//! [`Some`](../result/enum.Result.html),
|
||||
//! [`None`](../result/enum.Result.html)
|
||||
//! }.
|
||||
//! The ubiquitous `Result` type and its two [variants][book-enums],
|
||||
//! `Ok` and `Err`.
|
||||
//! * `std::slice::`[`SliceConcatExt`](../slice/trait.SliceConcatExt.html).
|
||||
//! An unstable extension to slices that shouldn't have to exist.
|
||||
//! * `std::string::`{
|
||||
//! [`String`](../string/struct.String.html),
|
||||
//! [`ToString`](../string/trait.ToString.html)
|
||||
//! }.
|
||||
//! Heap allocated strings.
|
||||
//! * `std::vec::`[`Vec`](../vec/struct.Vec.html).
|
||||
//! Heap allocated vectors.
|
||||
//!
|
||||
//! [book-traits]: ../../book/traits.html
|
||||
//! [book-closures]: ../../book/closures.html
|
||||
//! [book-dtor]: ../../book/drop.html
|
||||
//! [book-iter]: ../../book/iterators.html
|
||||
//! [book-enums]: ../../book/enums.html
|
||||
|
||||
#![stable(feature = "rust1", since = "1.0.0")]
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue