src/libcore/default.rs

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