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