library/core/src/default.rs

   1 //! The `Default` trait for types with a default value.
   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 #[const_trait]
 103 pub trait Default: Sized {
 104     /// Returns the "default value" for a type.
 105     ///
 106     /// Default values are often some kind of initial value, identity value, or anything else that
 107     /// may make sense as a default.
 108     ///
 109     /// # Examples
 110     ///
 111     /// Using built-in default values:
 112     ///
 113     /// ```
 114     /// let i: i8 = Default::default();
 115     /// let (x, y): (Option<String>, f64) = Default::default();
 116     /// let (a, b, (c, d)): (i32, u32, (bool, bool)) = Default::default();
 117     /// ```
 118     ///
 119     /// Making your own:
 120     ///
 121     /// ```
 122     /// # #[allow(dead_code)]
 123     /// enum Kind {
 124     ///     A,
 125     ///     B,
 126     ///     C,
 127     /// }
 128     ///
 129     /// impl Default for Kind {
 130     ///     fn default() -> Self { Kind::A }
 131     /// }
 132     /// ```
 133     #[stable(feature = "rust1", since = "1.0.0")]
 134     fn default() -> Self;
 135 }
 136
 137 /// Return the default value of a type according to the `Default` trait.
 138 ///
 139 /// The type to return is inferred from context; this is equivalent to
 140 /// `Default::default()` but shorter to type.
 141 ///
 142 /// For example:
 143 /// ```
 144 /// #![feature(default_free_fn)]
 145 ///
 146 /// use std::default::default;
 147 ///
 148 /// #[derive(Default)]
 149 /// struct AppConfig {
 150 ///     foo: FooConfig,
 151 ///     bar: BarConfig,
 152 /// }
 153 ///
 154 /// #[derive(Default)]
 155 /// struct FooConfig {
 156 ///     foo: i32,
 157 /// }
 158 ///
 159 /// #[derive(Default)]
 160 /// struct BarConfig {
 161 ///     bar: f32,
 162 ///     baz: u8,
 163 /// }
 164 ///
 165 /// fn main() {
 166 ///     let options = AppConfig {
 167 ///         foo: default(),
 168 ///         bar: BarConfig {
 169 ///             bar: 10.1,
 170 ///             ..default()
 171 ///         },
 172 ///     };
 173 /// }
 174 /// ```
 175 #[unstable(feature = "default_free_fn", issue = "73014")]
 176 #[must_use]
 177 #[inline]
 178 pub fn default<T: Default>() -> T {
 179     Default::default()
 180 }
 181
 182 /// Derive macro generating an impl of the trait `Default`.
 183 #[rustc_builtin_macro(Default, attributes(default))]
 184 #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
 185 #[allow_internal_unstable(core_intrinsics)]
 186 pub macro Default($item:item) {
 187     /* compiler built-in */
 188 }
 189
 190 macro_rules! default_impl {
 191     ($t:ty, $v:expr, $doc:tt) => {
 192         #[stable(feature = "rust1", since = "1.0.0")]
 193         #[rustc_const_unstable(feature = "const_default_impls", issue = "87864")]
 194         impl const Default for $t {
 195             #[inline]
 196             #[doc = $doc]
 197             fn default() -> $t {
 198                 $v
 199             }
 200         }
 201     };
 202 }
 203
 204 default_impl! { (), (), "Returns the default value of `()`" }
 205 default_impl! { bool, false, "Returns the default value of `false`" }
 206 default_impl! { char, '\x00', "Returns the default value of `\\x00`" }
 207
 208 default_impl! { usize, 0, "Returns the default value of `0`" }
 209 default_impl! { u8, 0, "Returns the default value of `0`" }
 210 default_impl! { u16, 0, "Returns the default value of `0`" }
 211 default_impl! { u32, 0, "Returns the default value of `0`" }
 212 default_impl! { u64, 0, "Returns the default value of `0`" }
 213 default_impl! { u128, 0, "Returns the default value of `0`" }
 214
 215 default_impl! { isize, 0, "Returns the default value of `0`" }
 216 default_impl! { i8, 0, "Returns the default value of `0`" }
 217 default_impl! { i16, 0, "Returns the default value of `0`" }
 218 default_impl! { i32, 0, "Returns the default value of `0`" }
 219 default_impl! { i64, 0, "Returns the default value of `0`" }
 220 default_impl! { i128, 0, "Returns the default value of `0`" }
 221
 222 default_impl! { f32, 0.0f32, "Returns the default value of `0.0`" }
 223 default_impl! { f64, 0.0f64, "Returns the default value of `0.0`" }