1 //! The `Default` trait for types which may have meaningful default values.
3 #![stable(feature = "rust1", since = "1.0.0")]
5 /// A trait for giving a type a useful default value.
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:
12 /// # #[allow(dead_code)]
13 /// struct SomeOptions {
19 /// How can we define some default values? You can use `Default`:
22 /// # #[allow(dead_code)]
23 /// #[derive(Default)]
24 /// struct SomeOptions {
30 /// let options: SomeOptions = Default::default();
34 /// Now, you get all of the default values. Rust implements `Default` for various primitives types.
36 /// If you want to override a particular option, but still retain the other defaults:
39 /// # #[allow(dead_code)]
40 /// # #[derive(Default)]
41 /// # struct SomeOptions {
46 /// let options = SomeOptions { foo: 42, ..Default::default() };
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.
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.
61 /// #[derive(Default)]
70 /// You cannot use the `#[default]` attribute on non-unit or non-exhaustive variants.
72 /// ## How can I implement `Default`?
74 /// Provide an implementation for the `default()` method that returns the value of
75 /// your type that should be the default:
78 /// # #![allow(dead_code)]
85 /// impl Default for Kind {
86 /// fn default() -> Self { Kind::A }
93 /// # #[allow(dead_code)]
94 /// #[derive(Default)]
95 /// struct SomeOptions {
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.
105 /// Default values are often some kind of initial value, identity value, or anything else that
106 /// may make sense as a default.
110 /// Using built-in default values:
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();
121 /// # #[allow(dead_code)]
128 /// impl Default for Kind {
129 /// fn default() -> Self { Kind::A }
132 #[stable(feature = "rust1", since = "1.0.0")]
133 fn default() -> Self;
136 /// Return the default value of a type according to the `Default` trait.
138 /// The type to return is inferred from context; this is equivalent to
139 /// `Default::default()` but shorter to type.
143 /// #![feature(default_free_fn)]
145 /// use std::default::default;
147 /// #[derive(Default)]
148 /// struct AppConfig {
153 /// #[derive(Default)]
154 /// struct FooConfig {
158 /// #[derive(Default)]
159 /// struct BarConfig {
165 /// let options = AppConfig {
174 #[unstable(feature = "default_free_fn", issue = "73014")]
177 pub fn default<T: Default>() -> T {
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 */
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 {
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`" }
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`" }
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`" }
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`" }