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")]
102pub 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 #[rustc_diagnostic_item = "default_fn"]
134 fn default() -> Self;
135}
136
137/// Derive macro generating an impl of the trait `Default`.
138#[rustc_builtin_macro(Default, attributes(default))]
139#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
140#[allow_internal_unstable(core_intrinsics)]
141pub macro Default($item:item) {
142 /* compiler built-in */
143}
144
145macro_rules! default_impl {
146 ($t:ty, $v:expr, $doc:tt) => {
147 #[stable(feature = "rust1", since = "1.0.0")]
148 impl Default for $t {
149 #[inline(always)]
150 #[doc = $doc]
151 fn default() -> $t {
152 $v
153 }
154 }
155 };
156}
157
158default_impl! { (), (), "Returns the default value of `()`" }
159default_impl! { bool, false, "Returns the default value of `false`" }
160default_impl! { char, '\x00', "Returns the default value of `\\x00`" }
161
162default_impl! { usize, 0, "Returns the default value of `0`" }
163default_impl! { u8, 0, "Returns the default value of `0`" }
164default_impl! { u16, 0, "Returns the default value of `0`" }
165default_impl! { u32, 0, "Returns the default value of `0`" }
166default_impl! { u64, 0, "Returns the default value of `0`" }
167default_impl! { u128, 0, "Returns the default value of `0`" }
168
169default_impl! { isize, 0, "Returns the default value of `0`" }
170default_impl! { i8, 0, "Returns the default value of `0`" }
171default_impl! { i16, 0, "Returns the default value of `0`" }
172default_impl! { i32, 0, "Returns the default value of `0`" }
173default_impl! { i64, 0, "Returns the default value of `0`" }
174default_impl! { i128, 0, "Returns the default value of `0`" }
175
176default_impl! { f32, 0.0f32, "Returns the default value of `0.0`" }
177default_impl! { f64, 0.0f64, "Returns the default value of `0.0`" }
178