library/std/src/prelude/mod.rs

   1 //! # The Rust Prelude
   2 //!
   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
  10 //! things, particularly traits, which are used in almost every single Rust
  11 //! program.
  12 //!
  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 //!
  20 //! [`std::io::prelude`]: crate::io::prelude
  21 //!
  22 //! The difference between 'the prelude' and these other preludes is that they
  23 //! are not automatically `use`'d, and must be imported manually. This is still
  24 //! easier than importing all of their constituent components.
  25 //!
  26 //! # Prelude contents
  27 //!
  28 //! The first version of the prelude is used in Rust 2015 and Rust 2018,
  29 //! and lives in [`std::prelude::v1`].
  30 //! [`std::prelude::rust_2015`] and [`std::prelude::rust_2018`] re-export this prelude.
  31 //! It re-exports the following:
  32 //!
  33 //! * <code>[std::marker]::{[Copy], [Send], [Sized], [Sync], [Unpin]}</code>,
  34 //!   marker traits that indicate fundamental properties of types.
  35 //! * <code>[std::ops]::{[Drop], [Fn], [FnMut], [FnOnce]}</code>, various
  36 //!   operations for both destructors and overloading `()`.
  37 //! * <code>[std::mem]::[drop][mem::drop]</code>, a convenience function for explicitly
  38 //!   dropping a value.
  39 //! * <code>[std::boxed]::[Box]</code>, a way to allocate values on the heap.
  40 //! * <code>[std::borrow]::[ToOwned]</code>, the conversion trait that defines
  41 //!   [`to_owned`], the generic method for creating an owned type from a
  42 //!   borrowed type.
  43 //! * <code>[std::clone]::[Clone]</code>, the ubiquitous trait that defines
  44 //!   [`clone`][Clone::clone], the method for producing a copy of a value.
  45 //! * <code>[std::cmp]::{[PartialEq], [PartialOrd], [Eq], [Ord]}</code>, the
  46 //!   comparison traits, which implement the comparison operators and are often
  47 //!   seen in trait bounds.
  48 //! * <code>[std::convert]::{[AsRef], [AsMut], [Into], [From]}</code>, generic
  49 //!   conversions, used by savvy API authors to create overloaded methods.
  50 //! * <code>[std::default]::[Default]</code>, types that have default values.
  51 //! * <code>[std::iter]::{[Iterator], [Extend], [IntoIterator], [DoubleEndedIterator], [ExactSizeIterator]}</code>,
  52 //!   iterators of various
  53 //!   kinds.
  54 //! * <code>[std::option]::[Option]::{[self][Option], [Some], [None]}</code>, a
  55 //!   type which expresses the presence or absence of a value. This type is so
  56 //!   commonly used, its variants are also exported.
  57 //! * <code>[std::result]::[Result]::{[self][Result], [Ok], [Err]}</code>, a type
  58 //!   for functions that may succeed or fail. Like [`Option`], its variants are
  59 //!   exported as well.
  60 //! * <code>[std::string]::{[String], [ToString]}</code>, heap-allocated strings.
  61 //! * <code>[std::vec]::[Vec]</code>, a growable, heap-allocated vector.
  62 //!
  63 //! The prelude used in Rust 2021, [`std::prelude::rust_2021`], includes all of the above,
  64 //! and in addition re-exports:
  65 //!
  66 //! * <code>[std::convert]::{[TryFrom], [TryInto]}</code>,
  67 //! * <code>[std::iter]::[FromIterator]</code>.
  68 //!
  69 //! [mem::drop]: crate::mem::drop
  70 //! [std::borrow]: crate::borrow
  71 //! [std::boxed]: crate::boxed
  72 //! [std::clone]: crate::clone
  73 //! [std::cmp]: crate::cmp
  74 //! [std::convert]: crate::convert
  75 //! [std::default]: crate::default
  76 //! [std::iter]: crate::iter
  77 //! [std::marker]: crate::marker
  78 //! [std::mem]: crate::mem
  79 //! [std::ops]: crate::ops
  80 //! [std::option]: crate::option
  81 //! [`std::prelude::v1`]: v1
  82 //! [`std::prelude::rust_2015`]: rust_2015
  83 //! [`std::prelude::rust_2018`]: rust_2018
  84 //! [`std::prelude::rust_2021`]: rust_2021
  85 //! [std::result]: crate::result
  86 //! [std::slice]: crate::slice
  87 //! [std::string]: crate::string
  88 //! [std::vec]: mod@crate::vec
  89 //! [TryFrom]: crate::convert::TryFrom
  90 //! [TryInto]: crate::convert::TryInto
  91 //! [FromIterator]: crate::iter::FromIterator
  92 //! [`to_owned`]: crate::borrow::ToOwned::to_owned
  93 //! [book-closures]: ../../book/ch13-01-closures.html
  94 //! [book-dtor]: ../../book/ch15-03-drop.html
  95 //! [book-enums]: ../../book/ch06-01-defining-an-enum.html
  96 //! [book-iter]: ../../book/ch13-02-iterators.html
  97
  98 #![stable(feature = "rust1", since = "1.0.0")]
  99
 100 pub mod v1;
 101
 102 /// The 2015 version of the prelude of The Rust Standard Library.
 103 ///
 104 /// See the [module-level documentation](self) for more.
 105 #[stable(feature = "prelude_2015", since = "1.55.0")]
 106 pub mod rust_2015 {
 107     #[stable(feature = "prelude_2015", since = "1.55.0")]
 108     #[doc(no_inline)]
 109     pub use super::v1::*;
 110 }
 111
 112 /// The 2018 version of the prelude of The Rust Standard Library.
 113 ///
 114 /// See the [module-level documentation](self) for more.
 115 #[stable(feature = "prelude_2018", since = "1.55.0")]
 116 pub mod rust_2018 {
 117     #[stable(feature = "prelude_2018", since = "1.55.0")]
 118     #[doc(no_inline)]
 119     pub use super::v1::*;
 120 }
 121
 122 /// The 2021 version of the prelude of The Rust Standard Library.
 123 ///
 124 /// See the [module-level documentation](self) for more.
 125 #[stable(feature = "prelude_2021", since = "1.55.0")]
 126 pub mod rust_2021 {
 127     #[stable(feature = "prelude_2021", since = "1.55.0")]
 128     #[doc(no_inline)]
 129     pub use super::v1::*;
 130
 131     #[stable(feature = "prelude_2021", since = "1.55.0")]
 132     #[doc(no_inline)]
 133     pub use core::prelude::rust_2021::*;
 134 }