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