src/libcore/default.rs

   1 //! The `Default` trait for types which may have meaningful default values.
   2
   3 #![stable(feature = "rust1", since = "1.0.0")]
   4
   5 /// A trait for giving a type a useful default value.
   6 ///
   7 /// Sometimes, you want to fall back to some kind of default value, and
   8 /// don't particularly care what it is. This comes up often with `struct`s
   9 /// that define a set of options:
  10 ///
  11 /// ```
  12 /// # #[allow(dead_code)]
  13 /// struct SomeOptions {
  14 ///     foo: i32,
  15 ///     bar: f32,
  16 /// }
  17 /// ```
  18 ///
  19 /// How can we define some default values? You can use `Default`:
  20 ///
  21 /// ```
  22 /// # #[allow(dead_code)]
  23 /// #[derive(Default)]
  24 /// struct SomeOptions {
  25 ///     foo: i32,
  26 ///     bar: f32,
  27 /// }
  28 ///
  29 /// fn main() {
  30 ///     let options: SomeOptions = Default::default();
  31 /// }
  32 /// ```
  33 ///
  34 /// Now, you get all of the default values. Rust implements `Default` for various primitives types.
  35 ///
  36 /// If you want to override a particular option, but still retain the other defaults:
  37 ///
  38 /// ```
  39 /// # #[allow(dead_code)]
  40 /// # #[derive(Default)]
  41 /// # struct SomeOptions {
  42 /// #     foo: i32,
  43 /// #     bar: f32,
  44 /// # }
  45 /// fn main() {
  46 ///     let options = SomeOptions { foo: 42, ..Default::default() };
  47 /// }
  48 /// ```
  49 ///
  50 /// ## Derivable
  51 ///
  52 /// This trait can be used with `#[derive]` if all of the type's fields implement
  53 /// `Default`. When `derive`d, it will use the default value for each field's type.
  54 ///
  55 /// ## How can I implement `Default`?
  56 ///
  57 /// Provides an implementation for the `default()` method that returns the value of
  58 /// your type that should be the default:
  59 ///
  60 /// ```
  61 /// # #![allow(dead_code)]
  62 /// enum Kind {
  63 ///     A,
  64 ///     B,
  65 ///     C,
  66 /// }
  67 ///
  68 /// impl Default for Kind {
  69 ///     fn default() -> Self { Kind::A }
  70 /// }
  71 /// ```
  72 ///
  73 /// # Examples
  74 ///
  75 /// ```
  76 /// # #[allow(dead_code)]
  77 /// #[derive(Default)]
  78 /// struct SomeOptions {
  79 ///     foo: i32,
  80 ///     bar: f32,
  81 /// }
  82 /// ```
  83 #[stable(feature = "rust1", since = "1.0.0")]
  84 pub trait Default: Sized {
  85     /// Returns the "default value" for a type.
  86     ///
  87     /// Default values are often some kind of initial value, identity value, or anything else that
  88     /// may make sense as a default.
  89     ///
  90     /// # Examples
  91     ///
  92     /// Using built-in default values:
  93     ///
  94     /// ```
  95     /// let i: i8 = Default::default();
  96     /// let (x, y): (Option<String>, f64) = Default::default();
  97     /// let (a, b, (c, d)): (i32, u32, (bool, bool)) = Default::default();
  98     /// ```
  99     ///
 100     /// Making your own:
 101     ///
 102     /// ```
 103     /// # #[allow(dead_code)]
 104     /// enum Kind {
 105     ///     A,
 106     ///     B,
 107     ///     C,
 108     /// }
 109     ///
 110     /// impl Default for Kind {
 111     ///     fn default() -> Self { Kind::A }
 112     /// }
 113     /// ```
 114     #[stable(feature = "rust1", since = "1.0.0")]
 115     fn default() -> Self;
 116 }
 117
 118 /// Derive macro generating an impl of the trait `Default`.
 119 #[rustc_builtin_macro]
 120 #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
 121 #[allow_internal_unstable(core_intrinsics)]
 122 pub macro Default($item:item) {
 123     /* compiler built-in */
 124 }
 125
 126 macro_rules! default_impl {
 127     ($t:ty, $v:expr, $doc:tt) => {
 128         #[stable(feature = "rust1", since = "1.0.0")]
 129         impl Default for $t {
 130             #[inline]
 131             #[doc = $doc]
 132             fn default() -> $t { $v }
 133         }
 134     }
 135 }
 136
 137 default_impl! { (), (), "Returns the default value of `()`" }
 138 default_impl! { bool, false, "Returns the default value of `false`" }
 139 default_impl! { char, '\x00', "Returns the default value of `\\x00`" }
 140
 141 default_impl! { usize, 0, "Returns the default value of `0`" }
 142 default_impl! { u8, 0, "Returns the default value of `0`" }
 143 default_impl! { u16, 0, "Returns the default value of `0`" }
 144 default_impl! { u32, 0, "Returns the default value of `0`" }
 145 default_impl! { u64, 0, "Returns the default value of `0`" }
 146 default_impl! { u128, 0, "Returns the default value of `0`" }
 147
 148 default_impl! { isize, 0, "Returns the default value of `0`" }
 149 default_impl! { i8, 0, "Returns the default value of `0`" }
 150 default_impl! { i16, 0, "Returns the default value of `0`" }
 151 default_impl! { i32, 0, "Returns the default value of `0`" }
 152 default_impl! { i64, 0, "Returns the default value of `0`" }
 153 default_impl! { i128, 0, "Returns the default value of `0`" }
 154
 155 default_impl! { f32, 0.0f32, "Returns the default value of `0.0`" }
 156 default_impl! { f64, 0.0f64, "Returns the default value of `0.0`" }