default.rs - source
Skip to main content core/ default.rs 1 //! The `Default` trait for types with a default value. 2 3 #![stable(feature = "rust1" , since = "1.0.0" )] 4 5 use crate ::ascii::Char as AsciiChar; 6 7 /// A trait for giving a type a useful default value. 8 /// 9 /// Sometimes, you want to fall back to some kind of default value, and 10 /// don't particularly care what it is. This comes up often with `struct`s 11 /// that define a set of options: 12 /// 13 /// ``` 14 /// # #[allow(dead_code)] 15 /// struct SomeOptions { 16 /// foo: i32, 17 /// bar: f32, 18 /// } 19 /// ``` 20 /// 21 /// How can we define some default values?
You can use `Default`: 22 /// 23 /// ``` 24 /// # #[allow(dead_code)] 25 /// #[derive(Default)] 26 /// struct SomeOptions { 27 /// foo: i32, 28 /// bar: f32, 29 /// } 30 /// 31 /// fn main() { 32 /// let options: SomeOptions = Default::default(); 33 /// } 34 /// ``` 35 /// 36 /// Now, you get all of the default values. Rust implements `Default` for various primitive types. 37 /// 38 /// If you want to override a particular option, but still retain the other defaults: 39 /// 40 /// ``` 41 /// # #[allow(dead_code)] 42 /// # #[derive(Default)] 43 /// # struct SomeOptions { 44 /// # foo: i32, 45 /// # bar: f32, 46 /// # } 47 /// fn main() { 48 /// let options = SomeOptions { foo: 42, ..Default::default() }; 49 /// } 50 /// ``` 51 /// 52 /// ## Derivable 53 /// 54 /// This trait can be used with `#[derive]` if all of the type's fields implement 55 /// `Default`.
When `derive`d, it will use the default value for each field's type. 56 /// 57 /// ### `enum`s 58 /// 59 /// When using `#[derive(Default)]` on an `enum`, you need to choose which unit variant will be 60 /// default. You do this by placing the `#[default]` attribute on the variant. 61 /// 62 /// ``` 63 /// #[derive(Default)] 64 /// enum Kind { 65 /// #[default] 66 /// A, 67 /// B, 68 /// C, 69 /// } 70 /// ``` 71 /// 72 /// You cannot use the `#[default]` attribute on non-unit or non-exhaustive variants.
73 /// 74 /// The `#[default]` attribute was stabilized in Rust 1.62.0. 75 /// 76 /// ## How can I implement `Default`? 77 /// 78 /// Provide an implementation for the `default()` method that returns the value of 79 /// your type that should be the default: 80 /// 81 /// ``` 82 /// # #![allow(dead_code)] 83 /// enum Kind { 84 /// A, 85 /// B, 86 /// C, 87 /// } 88 /// 89 /// impl Default for Kind { 90 /// fn default() -> Self { Kind::A } 91 /// } 92 /// ``` 93 /// 94 /// # Examples 95 /// 96 /// ``` 97 /// # #[allow(dead_code)] 98 /// #[derive(Default)] 99 /// struct SomeOptions { 100 /// foo: i32, 101 /// bar: f32, 102 /// } 103 /// ``` 104 #[rustc_diagnostic_item = "Default" ] 105 #[stable(feature = "rust1" , since = "1.0.0" )] 106 #[rustc_const_unstable(feature = "const_default" , issue = "143894" )] 107 pub const trait Default : Sized { 108 /// Returns the "default value" for a type.
109 /// 110 /// Default values are often some kind of initial value, identity value, or anything else that 111 /// may make sense as a default. 112 /// 113 /// # Examples 114 /// 115 /// Using built-in default values: 116 /// 117 /// ``` 118 /// let i: i8 = Default::default(); 119 /// let (x, y): (Option<String>, f64) = Default::default(); 120 /// let (a, b, (c, d)): (i32, u32, (bool, bool)) = Default::default(); 121 /// ``` 122 /// 123 /// Making your own: 124 /// 125 /// ``` 126 /// # #[allow(dead_code)] 127 /// enum Kind { 128 /// A, 129 /// B, 130 /// C, 131 /// } 132 /// 133 /// impl Default for Kind { 134 /// fn default() -> Self { Kind::A } 135 /// } 136 /// ``` 137 #[stable(feature = "rust1" , since = "1.0.0" )] 138 #[rustc_diagnostic_item = "default_fn" ] 139 fn default() -> Self ; 140 } 141 142 /// Derive macro generating an impl of the trait `Default`.
143 #[rustc_builtin_macro(Default, attributes(default))] 144 #[stable(feature = "builtin_macro_prelude" , since = "1.38.0" )] 145 #[allow_internal_unstable(core_intrinsics)] 146 pub macro Default ( $item :item) { 147 /* compiler built-in */ 148 } 149 150 macro_rules! default_impl { 151 ( $t :ty, $v :expr, $doc :tt) => { 152 #[stable(feature = "rust1" , since = "1.0.0" )] 153 #[rustc_const_unstable(feature = "const_default" , issue = "143894" )] 154 const impl Default for $t { 155 #[inline(always)] 156 #[doc = $doc ] 157 fn default() -> $t { 158 $v 159 } 160 } 161 }; 162 } 163 164 default_impl! { (), (), "Returns the default value of `()`" } 165 default_impl! { bool , false , "Returns the default value of `false`" } 166 default_impl! { char , '\x00' , "Returns the default value of `\\x00`" } 167 default_impl! { AsciiChar , AsciiChar::Null, "Returns the default value of `Null`" } 168 169 default_impl! { usize , 0 , "Returns the default value of `0`" } 170 default_impl! { u8 , 0 , "Returns the default value of `0`" } 171 default_impl! { u16 , 0 , "Returns the default value of `0`" } 172 default_impl! { u32 , 0 , "Returns the default value of `0`" } 173 default_impl! { u64 , 0 , "Returns the default value of `0`" } 174 default_impl! { u128 , 0 , "Returns the default value of `0`" } 175 176 default_impl! { isize , 0 , "Returns the default value of `0`" } 177 default_impl! { i8 , 0 , "Returns the default value of `0`" } 178 default_impl! { i16 , 0 , "Returns the default value of `0`" } 179 default_impl! { i32 , 0 , "Returns the default value of `0`" } 180 default_impl! { i64 , 0 , "Returns the default value of `0`" } 181 default_impl! { i128 , 0 , "Returns the default value of `0`" } 182 183 default_impl! { f16 , 0.0f16 , "Returns the default value of `0.0`" } 184 default_impl! { f32 , 0.0f32 , "Returns the default value of `0.0`" } 185 default_impl! { f64 , 0.0f64 , "Returns the default value of `0.0`" } 186 default_impl! { f128 , 0.0f128 , "Returns the default value of `0.0`" }