]>
Commit | Line | Data |
---|---|---|
5869c6ff | 1 | //! # The Rust Prelude |
1a4d82fc | 2 | //! |
92a42be0 SL |
3 | //! Rust comes with a variety of things in its standard library. However, if |
4 | //! you had to manually import every single thing that you used, it would be | |
5 | //! very verbose. But importing a lot of things that a program never uses isn't | |
6 | //! good either. A balance needs to be struck. | |
7 | //! | |
8 | //! The *prelude* is the list of things that Rust automatically imports into | |
9 | //! every Rust program. It's kept as small as possible, and is focused on | |
7453a54e | 10 | //! things, particularly traits, which are used in almost every single Rust |
92a42be0 SL |
11 | //! program. |
12 | //! | |
92a42be0 SL |
13 | //! # Other preludes |
14 | //! | |
15 | //! Preludes can be seen as a pattern to make using multiple types more | |
16 | //! convenient. As such, you'll find other preludes in the standard library, | |
17 | //! such as [`std::io::prelude`]. Various libraries in the Rust ecosystem may | |
18 | //! also define their own preludes. | |
19 | //! | |
3dfed10e | 20 | //! [`std::io::prelude`]: crate::io::prelude |
92a42be0 | 21 | //! |
9cc50fc6 | 22 | //! The difference between 'the prelude' and these other preludes is that they |
92a42be0 | 23 | //! are not automatically `use`'d, and must be imported manually. This is still |
7453a54e | 24 | //! easier than importing all of their constituent components. |
92a42be0 SL |
25 | //! |
26 | //! # Prelude contents | |
c1a9b12d SL |
27 | //! |
28 | //! The current version of the prelude (version 1) lives in | |
fc512014 | 29 | //! [`std::prelude::v1`], and re-exports the following: |
c1a9b12d | 30 | //! |
5869c6ff | 31 | //! * [`std::marker`]::{[`Copy`], [`Send`], [`Sized`], [`Sync`], [`Unpin`]}: |
fc512014 | 32 | //! marker traits that indicate fundamental properties of types. |
5869c6ff | 33 | //! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}: various |
7453a54e | 34 | //! operations for both destructors and overloading `()`. |
5869c6ff | 35 | //! * [`std::mem`]::[`drop`][`mem::drop`]: a convenience function for explicitly |
cc61c64b | 36 | //! dropping a value. |
5869c6ff XL |
37 | //! * [`std::boxed`]::[`Box`]: a way to allocate values on the heap. |
38 | //! * [`std::borrow`]::[`ToOwned`]: the conversion trait that defines | |
cc61c64b | 39 | //! [`to_owned`], the generic method for creating an owned type from a |
92a42be0 | 40 | //! borrowed type. |
5869c6ff | 41 | //! * [`std::clone`]::[`Clone`]: the ubiquitous trait that defines |
cc61c64b | 42 | //! [`clone`][`Clone::clone`], the method for producing a copy of a value. |
5869c6ff | 43 | //! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`]}: the |
92a42be0 SL |
44 | //! comparison traits, which implement the comparison operators and are often |
45 | //! seen in trait bounds. | |
5869c6ff | 46 | //! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}: generic |
92a42be0 SL |
47 | //! conversions, used by savvy API authors to create overloaded methods. |
48 | //! * [`std::default`]::[`Default`], types that have default values. | |
5869c6ff XL |
49 | //! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`], |
50 | //! [`DoubleEndedIterator`], [`ExactSizeIterator`]}: iterators of various | |
92a42be0 | 51 | //! kinds. |
fc512014 | 52 | //! * [`std::option`]::[`Option`]::{[`self`][`Option`], [`Some`], [`None`]}, a |
3dfed10e XL |
53 | //! type which expresses the presence or absence of a value. This type is so |
54 | //! commonly used, its variants are also exported. | |
5869c6ff | 55 | //! * [`std::result`]::[`Result`]::{[`self`][`Result`], [`Ok`], [`Err`]}: a type |
3dfed10e XL |
56 | //! for functions that may succeed or fail. Like [`Option`], its variants are |
57 | //! exported as well. | |
5869c6ff XL |
58 | //! * [`std::string`]::{[`String`], [`ToString`]}: heap-allocated strings. |
59 | //! * [`std::vec`]::[`Vec`]: a growable, heap-allocated vector. | |
c1a9b12d | 60 | //! |
3dfed10e XL |
61 | //! [`mem::drop`]: crate::mem::drop |
62 | //! [`std::borrow`]: crate::borrow | |
63 | //! [`std::boxed`]: crate::boxed | |
64 | //! [`std::clone`]: crate::clone | |
65 | //! [`std::cmp`]: crate::cmp | |
66 | //! [`std::convert`]: crate::convert | |
67 | //! [`std::default`]: crate::default | |
68 | //! [`std::iter`]: crate::iter | |
69 | //! [`std::marker`]: crate::marker | |
70 | //! [`std::mem`]: crate::mem | |
71 | //! [`std::ops`]: crate::ops | |
72 | //! [`std::option`]: crate::option | |
73 | //! [`std::prelude::v1`]: v1 | |
74 | //! [`std::result`]: crate::result | |
75 | //! [`std::slice`]: crate::slice | |
76 | //! [`std::string`]: crate::string | |
1b1a35ee | 77 | //! [`std::vec`]: mod@crate::vec |
3dfed10e | 78 | //! [`to_owned`]: crate::borrow::ToOwned::to_owned |
9fa01778 XL |
79 | //! [book-closures]: ../../book/ch13-01-closures.html |
80 | //! [book-dtor]: ../../book/ch15-03-drop.html | |
81 | //! [book-enums]: ../../book/ch06-01-defining-an-enum.html | |
82 | //! [book-iter]: ../../book/ch13-02-iterators.html | |
1a4d82fc | 83 | |
85aaf69f | 84 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 85 | |
1a4d82fc | 86 | pub mod v1; |
6a06907d XL |
87 | |
88 | /// The 2015 version of the prelude of The Rust Standard Library. | |
89 | /// | |
90 | /// See the [module-level documentation](self) for more. | |
91 | #[unstable(feature = "prelude_2015", issue = "none")] | |
92 | pub mod rust_2015 { | |
93 | #[unstable(feature = "prelude_2015", issue = "none")] | |
94 | #[doc(no_inline)] | |
95 | pub use super::v1::*; | |
96 | } | |
97 | ||
98 | /// The 2018 version of the prelude of The Rust Standard Library. | |
99 | /// | |
100 | /// See the [module-level documentation](self) for more. | |
101 | #[unstable(feature = "prelude_2018", issue = "none")] | |
102 | pub mod rust_2018 { | |
103 | #[unstable(feature = "prelude_2018", issue = "none")] | |
104 | #[doc(no_inline)] | |
105 | pub use super::v1::*; | |
106 | } | |
107 | ||
108 | /// The 2021 version of the prelude of The Rust Standard Library. | |
109 | /// | |
110 | /// See the [module-level documentation](self) for more. | |
111 | #[unstable(feature = "prelude_2021", issue = "none")] | |
112 | pub mod rust_2021 { | |
113 | #[unstable(feature = "prelude_2021", issue = "none")] | |
114 | #[doc(no_inline)] | |
115 | pub use super::v1::*; | |
116 | ||
117 | #[unstable(feature = "prelude_2021", issue = "none")] | |
118 | #[doc(no_inline)] | |
119 | pub use core::prelude::rust_2021::*; | |
120 | } |