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 /// ### `enum`s
  56 ///
  57 /// When using `#[derive(Default)]` on an `enum`, you need to choose which unit variant will be
  58 /// default. You do this by placing the `#[default]` attribute on the variant.
  59 ///
  60 /// ```
  61 /// #[derive(Default)]
  62 /// enum Kind {
  63 ///     #[default]
  64 ///     A,
  65 ///     B,
  66 ///     C,
  67 /// }
  68 /// ```
  69 ///
  70 /// You cannot use the `#[default]` attribute on non-unit or non-exhaustive variants.
  71 ///
  72 /// ## How can I implement `Default`?
  73 ///
  74 /// Provide an implementation for the `default()` method that returns the value of
  75 /// your type that should be the default:
  76 ///
  77 /// ```
  78 /// # #![allow(dead_code)]
  79 /// enum Kind {
  80 ///     A,
  81 ///     B,
  82 ///     C,
  83 /// }
  84 ///
  85 /// impl Default for Kind {
  86 ///     fn default() -> Self { Kind::A }
  87 /// }
  88 /// ```
  89 ///
  90 /// # Examples
  91 ///
  92 /// ```
  93 /// # #[allow(dead_code)]
  94 /// #[derive(Default)]
  95 /// struct SomeOptions {
  96 ///     foo: i32,
  97 ///     bar: f32,
  98 /// }
  99 /// ```
 100 #[cfg_attr(not(test), rustc_diagnostic_item = "Default")]
 101 #[stable(feature = "rust1", since = "1.0.0")]
 102 pub trait Default: Sized {
 103     /// Returns the "default value" for a type.
 104     ///
 105     /// Default values are often some kind of initial value, identity value, or anything else that
 106     /// may make sense as a default.
 107     ///
 108     /// # Examples
 109     ///
 110     /// Using built-in default values:
 111     ///
 112     /// ```
 113     /// let i: i8 = Default::default();
 114     /// let (x, y): (Option<String>, f64) = Default::default();
 115     /// let (a, b, (c, d)): (i32, u32, (bool, bool)) = Default::default();
 116     /// ```
 117     ///
 118     /// Making your own:
 119     ///
 120     /// ```
 121     /// # #[allow(dead_code)]
 122     /// enum Kind {
 123     ///     A,
 124     ///     B,
 125     ///     C,
 126     /// }
 127     ///
 128     /// impl Default for Kind {
 129     ///     fn default() -> Self { Kind::A }
 130     /// }
 131     /// ```
 132     #[stable(feature = "rust1", since = "1.0.0")]
 133     fn default() -> Self;
 134 }
 135
 136 /// Return the default value of a type according to the `Default` trait.
 137 ///
 138 /// The type to return is inferred from context; this is equivalent to
 139 /// `Default::default()` but shorter to type.
 140 ///
 141 /// For example:
 142 /// ```
 143 /// #![feature(default_free_fn)]
 144 ///
 145 /// use std::default::default;
 146 ///
 147 /// #[derive(Default)]
 148 /// struct AppConfig {
 149 ///     foo: FooConfig,
 150 ///     bar: BarConfig,
 151 /// }
 152 ///
 153 /// #[derive(Default)]
 154 /// struct FooConfig {
 155 ///     foo: i32,
 156 /// }
 157 ///
 158 /// #[derive(Default)]
 159 /// struct BarConfig {
 160 ///     bar: f32,
 161 ///     baz: u8,
 162 /// }
 163 ///
 164 /// fn main() {
 165 ///     let options = AppConfig {
 166 ///         foo: default(),
 167 ///         bar: BarConfig {
 168 ///             bar: 10.1,
 169 ///             ..default()
 170 ///         },
 171 ///     };
 172 /// }
 173 /// ```
 174 #[unstable(feature = "default_free_fn", issue = "73014")]
 175 #[must_use]
 176 #[inline]
 177 pub fn default<T: Default>() -> T {
 178     Default::default()
 179 }
 180
 181 /// Derive macro generating an impl of the trait `Default`.
 182 #[rustc_builtin_macro(Default, attributes(default))]
 183 #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
 184 #[allow_internal_unstable(core_intrinsics)]
 185 pub macro Default($item:item) {
 186     /* compiler built-in */
 187 }
 188
 189 macro_rules! default_impl {
 190     ($t:ty, $v:expr, $doc:tt) => {
 191         #[stable(feature = "rust1", since = "1.0.0")]
 192         #[rustc_const_unstable(feature = "const_default_impls", issue = "87864")]
 193         impl const Default for $t {
 194             #[inline]
 195             #[doc = $doc]
 196             fn default() -> $t {
 197                 $v
 198             }
 199         }
 200     };
 201 }
 202
 203 default_impl! { (), (), "Returns the default value of `()`" }
 204 default_impl! { bool, false, "Returns the default value of `false`" }
 205 default_impl! { char, '\x00', "Returns the default value of `\\x00`" }
 206
 207 default_impl! { usize, 0, "Returns the default value of `0`" }
 208 default_impl! { u8, 0, "Returns the default value of `0`" }
 209 default_impl! { u16, 0, "Returns the default value of `0`" }
 210 default_impl! { u32, 0, "Returns the default value of `0`" }
 211 default_impl! { u64, 0, "Returns the default value of `0`" }
 212 default_impl! { u128, 0, "Returns the default value of `0`" }
 213
 214 default_impl! { isize, 0, "Returns the default value of `0`" }
 215 default_impl! { i8, 0, "Returns the default value of `0`" }
 216 default_impl! { i16, 0, "Returns the default value of `0`" }
 217 default_impl! { i32, 0, "Returns the default value of `0`" }
 218 default_impl! { i64, 0, "Returns the default value of `0`" }
 219 default_impl! { i128, 0, "Returns the default value of `0`" }
 220
 221 default_impl! { f32, 0.0f32, "Returns the default value of `0.0`" }
 222 default_impl! { f64, 0.0f64, "Returns the default value of `0.0`" }