library/core/src/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 /// Provide 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 /// Return the default value of a type according to the `Default` trait.
 119 ///
 120 /// The type to return is inferred from context; this is equivalent to
 121 /// `Default::default()` but shorter to type.
 122 ///
 123 /// For example:
 124 /// ```
 125 /// #![feature(default_free_fn)]
 126 ///
 127 /// use std::default::default;
 128 ///
 129 /// #[derive(Default)]
 130 /// struct AppConfig {
 131 ///     foo: FooConfig,
 132 ///     bar: BarConfig,
 133 /// }
 134 ///
 135 /// #[derive(Default)]
 136 /// struct FooConfig {
 137 ///     foo: i32,
 138 /// }
 139 ///
 140 /// #[derive(Default)]
 141 /// struct BarConfig {
 142 ///     bar: f32,
 143 ///     baz: u8,
 144 /// }
 145 ///
 146 /// fn main() {
 147 ///     let options = AppConfig {
 148 ///         foo: default(),
 149 ///         bar: BarConfig {
 150 ///             bar: 10.1,
 151 ///             ..default()
 152 ///         },
 153 ///     };
 154 /// }
 155 /// ```
 156 #[unstable(feature = "default_free_fn", issue = "73014")]
 157 #[inline]
 158 pub fn default<T: Default>() -> T {
 159     Default::default()
 160 }
 161
 162 /// Derive macro generating an impl of the trait `Default`.
 163 #[rustc_builtin_macro]
 164 #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
 165 #[allow_internal_unstable(core_intrinsics)]
 166 pub macro Default($item:item) {
 167     /* compiler built-in */
 168 }
 169
 170 macro_rules! default_impl {
 171     ($t:ty, $v:expr, $doc:tt) => {
 172         #[stable(feature = "rust1", since = "1.0.0")]
 173         impl Default for $t {
 174             #[inline]
 175             #[doc = $doc]
 176             fn default() -> $t {
 177                 $v
 178             }
 179         }
 180     };
 181 }
 182
 183 default_impl! { (), (), "Returns the default value of `()`" }
 184 default_impl! { bool, false, "Returns the default value of `false`" }
 185 default_impl! { char, '\x00', "Returns the default value of `\\x00`" }
 186
 187 default_impl! { usize, 0, "Returns the default value of `0`" }
 188 default_impl! { u8, 0, "Returns the default value of `0`" }
 189 default_impl! { u16, 0, "Returns the default value of `0`" }
 190 default_impl! { u32, 0, "Returns the default value of `0`" }
 191 default_impl! { u64, 0, "Returns the default value of `0`" }
 192 default_impl! { u128, 0, "Returns the default value of `0`" }
 193
 194 default_impl! { isize, 0, "Returns the default value of `0`" }
 195 default_impl! { i8, 0, "Returns the default value of `0`" }
 196 default_impl! { i16, 0, "Returns the default value of `0`" }
 197 default_impl! { i32, 0, "Returns the default value of `0`" }
 198 default_impl! { i64, 0, "Returns the default value of `0`" }
 199 default_impl! { i128, 0, "Returns the default value of `0`" }
 200
 201 default_impl! { f32, 0.0f32, "Returns the default value of `0.0`" }
 202 default_impl! { f64, 0.0f64, "Returns the default value of `0.0`" }