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 //! Because `std` is required by most serious Rust software, it is
  14 //! imported at the topmost level of every crate by default, as if
  15 //! each crate contains the following:
  16 //!
  17 //! ```ignore
  18 //! extern crate std;
  19 //! ```
  20 //!
  21 //! This means that the contents of std can be accessed from any context
  22 //! with the `std::` path prefix, as in `use std::vec`, `use std::thread::spawn`,
  23 //! etc.
  24 //!
  25 //! Additionally, `std` contains a versioned *prelude* that reexports many of the
  26 //! most common traits, types, and functions. *The contents of the prelude are
  27 //! imported into every module by default*.  Implicitly, all modules behave as if
  28 //! they contained the following [`use` statement][book-use]:
  29 //!
  30 //! [book-use]: ../../book/crates-and-modules.html#importing-modules-with-use
  31 //!
  32 //! ```ignore
  33 //! use std::prelude::v1::*;
  34 //! ```
  35 //!
  36 //! The prelude is primarily concerned with exporting *traits* that
  37 //! are so pervasive that they would be onerous to import for every use,
  38 //! particularly those that are commonly mentioned in [generic type
  39 //! bounds][book-traits].
  40 //!
  41 //! The current version of the prelude (version 1) lives in
  42 //! [`std::prelude::v1`](v1/index.html), and reexports the following.
  43 //!
  44 //! * `std::marker::`{
  45 //!     [`Copy`](../marker/trait.Copy.html),
  46 //!     [`Send`](../marker/trait.Send.html),
  47 //!     [`Sized`](../marker/trait.Sized.html),
  48 //!     [`Sync`](../marker/trait.Sync.html)
  49 //!   }.
  50 //!   The marker traits indicate fundamental properties of types.
  51 //! * `std::ops::`{
  52 //!     [`Drop`](../ops/trait.Drop.html),
  53 //!     [`Fn`](../ops/trait.Fn.html),
  54 //!     [`FnMut`](../ops/trait.FnMut.html),
  55 //!     [`FnOnce`](../ops/trait.FnOnce.html)
  56 //!   }.
  57 //!   The [destructor][book-dtor] trait and the
  58 //!   [closure][book-closures] traits, reexported from the same
  59 //!   [module that also defines overloaded
  60 //!   operators](../ops/index.html).
  61 //! * `std::mem::`[`drop`](../mem/fn.drop.html).
  62 //!   A convenience function for explicitly dropping a value.
  63 //! * `std::boxed::`[`Box`](../boxed/struct.Box.html).
  64 //!   The owned heap pointer.
  65 //! * `std::borrow::`[`ToOwned`](../borrow/trait.ToOwned.html).
  66 //!   The conversion trait that defines `to_owned`, the generic method
  67 //!   for creating an owned type from a borrowed type.
  68 //! * `std::clone::`[`Clone`](../clone/trait.Clone.html).
  69 //!   The ubiquitous trait that defines `clone`, the method for
  70 //!   producing copies of values that are consider expensive to copy.
  71 //! * `std::cmp::`{
  72 //!     [`PartialEq`](../cmp/trait.PartialEq.html),
  73 //!     [`PartialOrd`](../cmp/trait.PartialOrd.html),
  74 //!     [`Eq`](../cmp/trait.Eq.html),
  75 //!     [`Ord`](../cmp/trait.Ord.html)
  76 //!   }.
  77 //!   The comparision traits, which implement the comparison operators
  78 //!   and are often seen in trait bounds.
  79 //! * `std::convert::`{
  80 //!     [`AsRef`](../convert/trait.AsRef.html),
  81 //!     [`AsMut`](../convert/trait.AsMut.html),
  82 //!     [`Into`](../convert/trait.Into.html),
  83 //!     [`From`](../convert/trait.From.html)
  84 //!   }.
  85 //!   Generic conversions, used by savvy API authors to create
  86 //!   overloaded methods.
  87 //! * `std::default::`[`Default`](../default/trait.Default).
  88 //!   Types that have default values.
  89 //! * `std::iter::`{
  90 //!     [`Iterator`](../iter/trait.Iterator.html),
  91 //!     [`Extend`](../iter/trait.Extend.html),
  92 //!     [`IntoIterator`](../iter/trait.IntoIterator.html),
  93 //!     [`DoubleEndedIterator`](../iter/trait.DoubleEndedIterator.html),
  94 //!     [`ExactSizeIterator`](../iter/trait.ExactSizeIterator.html)
  95 //!   }.
  96 //!   [Iterators][book-iter].
  97 //! * `std::option::Option::`{
  98 //!     [`self`](../option/enum.Option.html),
  99 //!     [`Some`](../option/enum.Option.html),
 100 //!     [`None`](../option/enum.Option.html)
 101 //!   }.
 102 //!   The ubiquitous `Option` type and its two [variants][book-enums],
 103 //!   `Some` and `None`.
 104 //! * `std::result::Result::`{
 105 //!     [`self`](../result/enum.Result.html),
 106 //!     [`Some`](../result/enum.Result.html),
 107 //!     [`None`](../result/enum.Result.html)
 108 //!   }.
 109 //!   The ubiquitous `Result` type and its two [variants][book-enums],
 110 //!   `Ok` and `Err`.
 111 //! * `std::slice::`[`SliceConcatExt`](../slice/trait.SliceConcatExt.html).
 112 //!   An unstable extension to slices that shouldn't have to exist.
 113 //! * `std::string::`{
 114 //!     [`String`](../string/struct.String.html),
 115 //!     [`ToString`](../string/trait.ToString.html)
 116 //!   }.
 117 //!   Heap allocated strings.
 118 //! * `std::vec::`[`Vec`](../vec/struct.Vec.html).
 119 //!   Heap allocated vectors.
 120 //!
 121 //! [book-traits]: ../../book/traits.html
 122 //! [book-closures]: ../../book/closures.html
 123 //! [book-dtor]: ../../book/drop.html
 124 //! [book-iter]: ../../book/iterators.html
 125 //! [book-enums]: ../../book/enums.html
 126
 127 #![stable(feature = "rust1", since = "1.0.0")]
 128
 129 pub mod v1;