]> git.proxmox.com Git - rustc.git/blob - src/libstd/prelude/mod.rs
Imported Upstream version 1.9.0+dfsg1
[rustc.git] / src / libstd / prelude / mod.rs
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
11 //! The Rust Prelude.
12 //!
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, particularly traits, which are used in almost every single Rust
21 //! program.
22 //!
23 //! On a technical level, Rust inserts
24 //!
25 //! ```ignore
26 //! extern crate std;
27 //! ```
28 //!
29 //! into the crate root of every crate, and
30 //!
31 //! ```ignore
32 //! use std::prelude::v1::*;
33 //! ```
34 //!
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 difference 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 constituent components.
49 //!
50 //! # Prelude contents
51 //!
52 //! The current version of the prelude (version 1) lives in
53 //! [`std::prelude::v1`], and reexports the following.
54 //!
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 destructors 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.
88 //!
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
139 //! [book-closures]: ../../book/closures.html
140 //! [book-dtor]: ../../book/drop.html
141 //! [book-enums]: ../../book/enums.html
142 //! [book-iter]: ../../book/iterators.html
143
144 #![stable(feature = "rust1", since = "1.0.0")]
145
146 pub mod v1;