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 current version of the prelude (version 1) lives in
  29 //! [`std::prelude::v1`], and re-exports the following.
  30 //!
  31 //! * [`std::marker`]::{[`Copy`], [`Send`], [`Sized`], [`Sync`], [`Unpin`]}. The
  32 //!   marker traits indicate fundamental properties of types.
  33 //! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}. Various
  34 //!   operations for both destructors and overloading `()`.
  35 //! * [`std::mem`]::[`drop`][`mem::drop`], a convenience function for explicitly
  36 //!   dropping a value.
  37 //! * [`std::boxed`]::[`Box`], a way to allocate values on the heap.
  38 //! * [`std::borrow`]::[`ToOwned`], The conversion trait that defines
  39 //!   [`to_owned`], the generic method for creating an owned type from a
  40 //!   borrowed type.
  41 //! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines
  42 //!   [`clone`][`Clone::clone`], the method for producing a copy of a value.
  43 //! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] }. The
  44 //!   comparison traits, which implement the comparison operators and are often
  45 //!   seen in trait bounds.
  46 //! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}. Generic
  47 //!   conversions, used by savvy API authors to create overloaded methods.
  48 //! * [`std::default`]::[`Default`], types that have default values.
  49 //! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`],
  50 //!   [`DoubleEndedIterator`], [`ExactSizeIterator`]}. Iterators of various
  51 //!   kinds.
  52 //! * [`std::option`]::[`Option`]::{[`self`][`Option`], [`Some`], [`None`]}. A
  53 //!   type which expresses the presence or absence of a value. This type is so
  54 //!   commonly used, its variants are also exported.
  55 //! * [`std::result`]::[`Result`]::{[`self`][`Result`], [`Ok`], [`Err`]}. A type
  56 //!   for functions that may succeed or fail. Like [`Option`], its variants are
  57 //!   exported as well.
  58 //! * [`std::string`]::{[`String`], [`ToString`]}, heap allocated strings.
  59 //! * [`std::vec`]::[`Vec`], a growable, heap-allocated
  60 //!   vector.
  61 //!
  62 //! [`mem::drop`]: crate::mem::drop
  63 //! [`std::borrow`]: crate::borrow
  64 //! [`std::boxed`]: crate::boxed
  65 //! [`std::clone`]: crate::clone
  66 //! [`std::cmp`]: crate::cmp
  67 //! [`std::convert`]: crate::convert
  68 //! [`std::default`]: crate::default
  69 //! [`std::iter`]: crate::iter
  70 //! [`std::marker`]: crate::marker
  71 //! [`std::mem`]: crate::mem
  72 //! [`std::ops`]: crate::ops
  73 //! [`std::option`]: crate::option
  74 //! [`std::prelude::v1`]: v1
  75 //! [`std::result`]: crate::result
  76 //! [`std::slice`]: crate::slice
  77 //! [`std::string`]: crate::string
  78 //! [`std::vec`]: ../vec/index.html
  79 //! [`to_owned`]: crate::borrow::ToOwned::to_owned
  80 //! [book-closures]: ../../book/ch13-01-closures.html
  81 //! [book-dtor]: ../../book/ch15-03-drop.html
  82 //! [book-enums]: ../../book/ch06-01-defining-an-enum.html
  83 //! [book-iter]: ../../book/ch13-02-iterators.html
  84
  85 #![stable(feature = "rust1", since = "1.0.0")]
  86
  87 pub mod v1;