Skip to content

Commit 5f6d7cf

Browse files
authored
Rollup merge of #134855 - estebank:default-field-values-unstable-docs, r=jieyouxu
Add `default_field_values` entry to unstable book Tracking issue: #132162 RFC: https://github.com/rust-lang/rfcs/blob/master/text/3681-default-field-values.md
2 parents 3806127 + 13e8876 commit 5f6d7cf

File tree

1 file changed

+93
-0
lines changed

1 file changed

+93
-0
lines changed
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
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

Comments
 (0)