[rustc.git] / src / libstd / prelude / mod.rs

// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! The Rust Prelude
//!
//! 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;
//! ```
//!
//! into the crate root of every crate, and
//!
//! ```ignore
//! use std::prelude::v1::*;
//! ```
//!
//! 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`], and reexports the following.
//!
//! * [`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.
//!
//! [`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-enums]: ../../book/enums.html
//! [book-iter]: ../../book/iterators.html

#![stable(feature = "rust1", since = "1.0.0")]

pub mod v1;
Commit	Line	Data
1a4d82fc JJ	1	// Copyright 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
bd371182	11	//! The Rust Prelude
1a4d82fc	12	//!
92a42be0 SL	13	//! Rust comes with a variety of things in its standard library. However, if
	14	//! you had to manually import every single thing that you used, it would be
	15	//! very verbose. But importing a lot of things that a program never uses isn't
	16	//! good either. A balance needs to be struck.
	17	//!
	18	//! The prelude is the list of things that Rust automatically imports into
	19	//! every Rust program. It's kept as small as possible, and is focused on
	20	//! things, particuarly traits, which are used in almost every single Rust
	21	//! program.
	22	//!
	23	//! On a technical level, Rust inserts
1a4d82fc JJ	24	//!
	25	//! ```ignore
	26	//! extern crate std;
	27	//! ```
	28	//!
92a42be0	29	//! into the crate root of every crate, and
1a4d82fc JJ	30	//!
	31	//! ```ignore
	32	//! use std::prelude::v1::*;
	33	//! ```
	34	//!
92a42be0 SL	35	//! into every module.
	36	//!
	37	//! # Other preludes
	38	//!
	39	//! Preludes can be seen as a pattern to make using multiple types more
	40	//! convenient. As such, you'll find other preludes in the standard library,
	41	//! such as [`std::io::prelude`]. Various libraries in the Rust ecosystem may
	42	//! also define their own preludes.
	43	//!
	44	//! [`std::io::prelude`]: ../io/prelude/index.html
	45	//!
	46	//! The differece between 'the prelude' and these other preludes is that they
	47	//! are not automatically `use`'d, and must be imported manually. This is still
	48	//! easier than importing all of their consitutent components.
	49	//!
	50	//! # Prelude contents
c1a9b12d SL	51	//!
c1a9b12d SL	52	//! The current version of the prelude (version 1) lives in
92a42be0	53	//! [`std::prelude::v1`], and reexports the following.
c1a9b12d	54	//!
92a42be0 SL	55	//! * [`std::marker`]::{[`Copy`], [`Send`], [`Sized`], [`Sync`]}. The marker
	56	//! traits indicate fundamental properties of types.
	57	//! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}. Various
	58	//! operations for both destuctors and overloading `()`.
	59	//! * [`std::mem`]::[`drop`], a convenience function for explicitly dropping a
	60	//! value.
	61	//! * [`std::boxed`]::[`Box`], a way to allocate values on the heap.
	62	//! * [`std::borrow`]::[`ToOwned`], The conversion trait that defines
	63	//! [`to_owned()`], the generic method for creating an owned type from a
	64	//! borrowed type.
	65	//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines [`clone()`],
	66	//! the method for producing a copy of a value.
	67	//! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] }. The
	68	//! comparison traits, which implement the comparison operators and are often
	69	//! seen in trait bounds.
	70	//! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}. Generic
	71	//! conversions, used by savvy API authors to create overloaded methods.
	72	//! * [`std::default`]::[`Default`], types that have default values.
	73	//! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`],
	74	//! [`DoubleEndedIterator`], [`ExactSizeIterator`]}. Iterators of various
	75	//! kinds.
	76	//! * [`std::option`]::[`Option`]::{`self`, `Some`, `None`}. A type which
	77	//! expresses the presence or absence of a value. This type is so commonly
	78	//! used, its variants are also exported.
	79	//! * [`std::result`]::[`Result`]::{`self`, `Ok`, `Err`}. A type for functions
	80	//! that may succeed or fail. Like [`Option`], its variants are exported as
	81	//! well.
	82	//! * [`std::slice`]::[`SliceConcatExt`], a trait that exists for technical
	83	//! reasons, but shouldn't have to exist. It provides a few useful methods on
	84	//! slices.
	85	//! * [`std::string`]::{[`String`], [`ToString`]}, heap allocated strings.
	86	//! * [`std::vec`]::[`Vec`](../vec/struct.Vec.html), a growable, heap-allocated
	87	//! vector.
c1a9b12d	88	//!
92a42be0 SL	89	//! [`AsMut`]: ../convert/trait.AsMut.html
	90	//! [`AsRef`]: ../convert/trait.AsRef.html
	91	//! [`Box`]: ../boxed/struct.Box.html
	92	//! [`Clone`]: ../clone/trait.Clone.html
	93	//! [`Copy`]: ../marker/trait.Copy.html
	94	//! [`Default`]: ../default/trait.Default.html
	95	//! [`DoubleEndedIterator`]: ../iter/trait.DoubleEndedIterator.html
	96	//! [`Drop`]: ../ops/trait.Drop.html
	97	//! [`Eq`]: ../cmp/trait.Eq.html
	98	//! [`ExactSizeIterator`]: ../iter/trait.ExactSizeIterator.html
	99	//! [`Extend`]: ../iter/trait.Extend.html
	100	//! [`FnMut`]: ../ops/trait.FnMut.html
	101	//! [`FnOnce`]: ../ops/trait.FnOnce.html
	102	//! [`Fn`]: ../ops/trait.Fn.html
	103	//! [`From`]: ../convert/trait.From.html
	104	//! [`IntoIterator`]: ../iter/trait.IntoIterator.html
	105	//! [`Into`]: ../convert/trait.Into.html
	106	//! [`Iterator`]: ../iter/trait.Iterator.html
	107	//! [`Option`]: ../option/enum.Option.html
	108	//! [`Ord`]: ../cmp/trait.Ord.html
	109	//! [`PartialEq`]: ../cmp/trait.PartialEq.html
	110	//! [`PartialOrd`]: ../cmp/trait.PartialOrd.html
	111	//! [`Result`]: ../result/enum.Result.html
	112	//! [`Send`]: ../marker/trait.Send.html
	113	//! [`Sized`]: ../marker/trait.Sized.html
	114	//! [`SliceConcatExt`]: ../slice/trait.SliceConcatExt.html
	115	//! [`String`]: ../string/struct.String.html
	116	//! [`Sync`]: ../marker/trait.Sync.html
	117	//! [`ToOwned`]: ../borrow/trait.ToOwned.html
	118	//! [`ToString`]: ../string/trait.ToString.html
	119	//! [`Vec`]: ../vec/struct.Vec.html
	120	//! [`clone()`]: ../clone/trait.Clone.html#tymethod.clone
	121	//! [`drop`]: ../mem/fn.drop.html
	122	//! [`std::borrow`]: ../borrow/index.html
	123	//! [`std::boxed`]: ../boxed/index.html
	124	//! [`std::clone`]: ../clone/index.html
	125	//! [`std::cmp`]: ../cmp/index.html
	126	//! [`std::convert`]: ../convert/index.html
	127	//! [`std::default`]: ../default/index.html
	128	//! [`std::iter`]: ../iter/index.html
	129	//! [`std::marker`]: ../marker/index.html
	130	//! [`std::mem`]: ../mem/index.html
	131	//! [`std::ops`]: ../ops/index.html
	132	//! [`std::option`]: ../option/index.html
	133	//! [`std::prelude::v1`]: v1/index.html
	134	//! [`std::result`]: ../result/index.html
	135	//! [`std::slice`]: ../slice/index.html
	136	//! [`std::string`]: ../string/index.html
	137	//! [`std::vec`]: ../vec/index.html
	138	//! [`to_owned()`]: ../borrow/trait.ToOwned.html#tymethod.to_owned
c1a9b12d SL	139	//! [book-closures]: ../../book/closures.html
c1a9b12d SL	140	//! [book-dtor]: ../../book/drop.html
c1a9b12d	141	//! [book-enums]: ../../book/enums.html
92a42be0	142	//! [book-iter]: ../../book/iterators.html
1a4d82fc	143
85aaf69f	144	#![stable(feature = "rust1", since = "1.0.0")]
1a4d82fc	145
1a4d82fc	146	pub mod v1;