diff --git a/src/libstd/prelude/mod.rs b/src/libstd/prelude/mod.rs index 08227cfb35322..3ff1798159efa 100644 --- a/src/libstd/prelude/mod.rs +++ b/src/libstd/prelude/mod.rs @@ -10,119 +10,136 @@ //! The Rust Prelude //! -//! Because `std` is required by most serious Rust software, it is -//! imported at the topmost level of every crate by default, as if -//! each crate contains the following: +//! Rust comes with a variety of things in its standard library. However, if +//! you had to manually import every single thing that you used, it would be +//! very verbose. But importing a lot of things that a program never uses isn't +//! good either. A balance needs to be struck. +//! +//! The *prelude* is the list of things that Rust automatically imports into +//! every Rust program. It's kept as small as possible, and is focused on +//! things, particuarly traits, which are used in almost every single Rust +//! program. +//! +//! On a technical level, Rust inserts //! //! ```ignore //! extern crate std; //! ``` //! -//! This means that the contents of std can be accessed from any context -//! with the `std::` path prefix, as in `use std::vec`, `use std::thread::spawn`, -//! etc. -//! -//! 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 +//! into the crate root of every crate, and //! //! ```ignore //! use std::prelude::v1::*; //! ``` //! -//! 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]. +//! into every module. +//! +//! # Other preludes +//! +//! Preludes can be seen as a pattern to make using multiple types more +//! convenient. As such, you'll find other preludes in the standard library, +//! such as [`std::io::prelude`]. Various libraries in the Rust ecosystem may +//! also define their own preludes. +//! +//! [`std::io::prelude`]: ../io/prelude/index.html +//! +//! The differece between 'the prelude' and these other preludes is that they +//! are not automatically `use`'d, and must be imported manually. This is still +//! easier than importing all of their consitutent components. +//! +//! # Prelude contents //! //! The current version of the prelude (version 1) lives in -//! [`std::prelude::v1`](v1/index.html), and reexports the following. +//! [`std::prelude::v1`], 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 comparison 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.html). -//! 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), -//! [`Ok`](../result/enum.Result.html), -//! [`Err`](../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. +//! * [`std::marker`]::{[`Copy`], [`Send`], [`Sized`], [`Sync`]}. The marker +//! traits indicate fundamental properties of types. +//! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}. Various +//! operations for both destuctors and overloading `()`. +//! * [`std::mem`]::[`drop`], a convenience function for explicitly dropping a +//! value. +//! * [`std::boxed`]::[`Box`], a way to allocate values on the heap. +//! * [`std::borrow`]::[`ToOwned`], The conversion trait that defines +//! [`to_owned()`], the generic method for creating an owned type from a +//! borrowed type. +//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines [`clone()`], +//! the method for producing a copy of a value. +//! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] }. The +//! comparison traits, which implement the comparison operators and are often +//! seen in trait bounds. +//! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}. Generic +//! conversions, used by savvy API authors to create overloaded methods. +//! * [`std::default`]::[`Default`], types that have default values. +//! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`], +//! [`DoubleEndedIterator`], [`ExactSizeIterator`]}. Iterators of various +//! kinds. +//! * [`std::option`]::[`Option`]::{`self`, `Some`, `None`}. A type which +//! expresses the presence or absence of a value. This type is so commonly +//! used, its variants are also exported. +//! * [`std::result`]::[`Result`]::{`self`, `Ok`, `Err`}. A type for functions +//! that may succeed or fail. Like [`Option`], its variants are exported as +//! well. +//! * [`std::slice`]::[`SliceConcatExt`], a trait that exists for technical +//! reasons, but shouldn't have to exist. It provides a few useful methods on +//! slices. +//! * [`std::string`]::{[`String`], [`ToString`]}, heap allocated strings. +//! * [`std::vec`]::[`Vec`](../vec/struct.Vec.html), a growable, heap-allocated +//! vector. //! -//! [book-traits]: ../../book/traits.html +//! [`AsMut`]: ../convert/trait.AsMut.html +//! [`AsRef`]: ../convert/trait.AsRef.html +//! [`Box`]: ../boxed/struct.Box.html +//! [`Clone`]: ../clone/trait.Clone.html +//! [`Copy`]: ../marker/trait.Copy.html +//! [`Default`]: ../default/trait.Default.html +//! [`DoubleEndedIterator`]: ../iter/trait.DoubleEndedIterator.html +//! [`Drop`]: ../ops/trait.Drop.html +//! [`Eq`]: ../cmp/trait.Eq.html +//! [`ExactSizeIterator`]: ../iter/trait.ExactSizeIterator.html +//! [`Extend`]: ../iter/trait.Extend.html +//! [`FnMut`]: ../ops/trait.FnMut.html +//! [`FnOnce`]: ../ops/trait.FnOnce.html +//! [`Fn`]: ../ops/trait.Fn.html +//! [`From`]: ../convert/trait.From.html +//! [`IntoIterator`]: ../iter/trait.IntoIterator.html +//! [`Into`]: ../convert/trait.Into.html +//! [`Iterator`]: ../iter/trait.Iterator.html +//! [`Option`]: ../option/enum.Option.html +//! [`Ord`]: ../cmp/trait.Ord.html +//! [`PartialEq`]: ../cmp/trait.PartialEq.html +//! [`PartialOrd`]: ../cmp/trait.PartialOrd.html +//! [`Result`]: ../result/enum.Result.html +//! [`Send`]: ../marker/trait.Send.html +//! [`Sized`]: ../marker/trait.Sized.html +//! [`SliceConcatExt`]: ../slice/trait.SliceConcatExt.html +//! [`String`]: ../string/struct.String.html +//! [`Sync`]: ../marker/trait.Sync.html +//! [`ToOwned`]: ../borrow/trait.ToOwned.html +//! [`ToString`]: ../string/trait.ToString.html +//! [`Vec`]: ../vec/struct.Vec.html +//! [`clone()`]: ../clone/trait.Clone.html#tymethod.clone +//! [`drop`]: ../mem/fn.drop.html +//! [`std::borrow`]: ../borrow/index.html +//! [`std::boxed`]: ../boxed/index.html +//! [`std::clone`]: ../clone/index.html +//! [`std::cmp`]: ../cmp/index.html +//! [`std::convert`]: ../convert/index.html +//! [`std::default`]: ../default/index.html +//! [`std::iter`]: ../iter/index.html +//! [`std::marker`]: ../marker/index.html +//! [`std::mem`]: ../mem/index.html +//! [`std::ops`]: ../ops/index.html +//! [`std::option`]: ../option/index.html +//! [`std::prelude::v1`]: v1/index.html +//! [`std::result`]: ../result/index.html +//! [`std::slice`]: ../slice/index.html +//! [`std::string`]: ../string/index.html +//! [`std::vec`]: ../vec/index.html +//! [`to_owned()`]: ../borrow/trait.ToOwned.html#tymethod.to_owned //! [book-closures]: ../../book/closures.html //! [book-dtor]: ../../book/drop.html -//! [book-iter]: ../../book/iterators.html //! [book-enums]: ../../book/enums.html +//! [book-iter]: ../../book/iterators.html #![stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/prelude/v1.rs b/src/libstd/prelude/v1.rs index 46c0103e08764..9ca5b445c86a9 100644 --- a/src/libstd/prelude/v1.rs +++ b/src/libstd/prelude/v1.rs @@ -9,6 +9,8 @@ // except according to those terms. //! The first version of the prelude of The Rust Standard Library. +//! +//! See the [module-level documentation](../index.html) for more. #![stable(feature = "rust1", since = "1.0.0")]