|
| 1 | +# `default_field_values` |
| 2 | + |
| 3 | +The tracking issue for this feature is: [#132162] |
| 4 | + |
| 5 | +[#132162]: https://github.com/rust-lang/rust/issues/132162 |
| 6 | + |
| 7 | +The RFC for this feature is: [#3681] |
| 8 | + |
| 9 | +[#3681]: https://github.com/rust-lang/rfcs/blob/master/text/3681-default-field-values.md |
| 10 | + |
| 11 | +------------------------ |
| 12 | + |
| 13 | +The `default_field_values` feature allows users to specify a const value for |
| 14 | +individual fields in struct definitions, allowing those to be omitted from |
| 15 | +initializers. |
| 16 | + |
| 17 | +## Examples |
| 18 | + |
| 19 | +```rust |
| 20 | +#![feature(default_field_values)] |
| 21 | + |
| 22 | +#[derive(Default)] |
| 23 | +struct Pet { |
| 24 | + name: Option<String>, // impl Default for Pet will use Default::default() for name |
| 25 | + age: i128 = 42, // impl Default for Pet will use the literal 42 for age |
| 26 | +} |
| 27 | + |
| 28 | +fn main() { |
| 29 | + let a = Pet { name: Some(String::new()), .. }; // Pet { name: Some(""), age: 42 } |
| 30 | + let b = Pet::default(); // Pet { name: None, age: 42 } |
| 31 | + assert_eq!(a.age, b.age); |
| 32 | + // The following would be a compilation error: `name` needs to be specified |
| 33 | + // let _ = Pet { .. }; |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +## `#[derive(Default)]` |
| 38 | + |
| 39 | +When deriving Default, the provided values are then used. On enum variants, |
| 40 | +the variant must still be marked with `#[default]` and have all its fields |
| 41 | +with default values. |
| 42 | + |
| 43 | +```rust |
| 44 | +#![feature(default_field_values)] |
| 45 | + |
| 46 | +#[derive(Default)] |
| 47 | +enum A { |
| 48 | + #[default] |
| 49 | + B { |
| 50 | + x: i32 = 0, |
| 51 | + y: i32 = 0, |
| 52 | + }, |
| 53 | + C, |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +## Enum variants |
| 58 | + |
| 59 | +This feature also supports enum variants for both specifying default values |
| 60 | +and `#[derive(Default)]`. |
| 61 | + |
| 62 | +## Interaction with `#[non_exhaustive]` |
| 63 | + |
| 64 | +A struct or enum variant marked with `#[non_exhaustive]` is not allowed to |
| 65 | +have default field values. |
| 66 | + |
| 67 | +## Lints |
| 68 | + |
| 69 | +When manually implementing the `Default` trait for a type that has default |
| 70 | +field values, if any of these are overriden in the impl the |
| 71 | +`default_overrides_default_fields` lint will trigger. This lint is in place |
| 72 | +to avoid surprising diverging behavior between `S { .. }` and |
| 73 | +`S::default()`, where using the same type in both ways could result in |
| 74 | +different values. The appropriate way to write a manual `Default` |
| 75 | +implementation is to use the functional update syntax: |
| 76 | + |
| 77 | +```rust |
| 78 | +#![feature(default_field_values)] |
| 79 | + |
| 80 | +struct Pet { |
| 81 | + name: String, |
| 82 | + age: i128 = 42, // impl Default for Pet will use the literal 42 for age |
| 83 | +} |
| 84 | + |
| 85 | +impl Default for Pet { |
| 86 | + fn default() -> Pet { |
| 87 | + Pet { |
| 88 | + name: "no-name".to_string(), |
| 89 | + .. |
| 90 | + } |
| 91 | + } |
| 92 | +} |
| 93 | +``` |
0 commit comments