Add docs for field default values

Author: bluebear94

Diff for: src/expressions/struct-expr.md

@@ -22,7 +22,7 @@ r[expr.struct.syntax]
 >    )
 >
 > _StructBase_ :\
->    `..` [_Expression_]
+> &nbsp;&nbsp; `..` [_Expression_]<sup>?</sup>
 >
 > _StructExprTuple_ :\
 > &nbsp;&nbsp; [_PathInExpression_] `(`\
@@ -62,29 +62,6 @@ The field name is separated from its value with a colon.
 r[expr.struct.field.union-constraint]
 A value of a [union] type can only be created using this syntax, and it must specify exactly one field.
 
-r[expr.struct.update]
-## Functional update syntax
-
-r[expr.struct.update.intro]
-A struct expression that constructs a value of a struct type can terminate with the syntax `..` followed by an expression to denote a functional update.
-
-r[expr.struct.update.base-same-type]
-The expression following `..` (the base) must have the same struct type as the new struct type being formed.
-
-r[expr.struct.update.fields]
-The entire expression uses the given values for the fields that were specified and moves or copies the remaining fields from the base expression.
-
-r[expr.struct.update.visibility-constraint]
-As with all struct expressions, all of the fields of the struct must be [visible], even those not explicitly named.
-
-```rust
-# struct Point3d { x: i32, y: i32, z: i32 }
-let mut base = Point3d {x: 1, y: 2, z: 3};
-let y_ref = &mut base.y;
-Point3d {y: 0, z: 10, .. base}; // OK, only base.x is accessed
-drop(y_ref);
-```
-
 r[expr.struct.brace-restricted-positions]
 Struct expressions with curly braces can't be used directly in a [loop] or [if] expression's head, or in the [scrutinee] of an [if let] or [match] expression.
 However, struct expressions can be used in these situations if they are within another expression, for example inside [parentheses].
@@ -142,6 +119,52 @@ let a = Gamma;  // Gamma unit value.
 let b = Gamma{};  // Exact same value as `a`.
 ```
 
+r[expr.struct.update]
+## Functional update syntax
+
+r[expr.struct.update.intro]
+A struct expression that constructs a value of a struct type can terminate with the syntax `..` followed by an expression to denote a functional update.
+
+r[expr.struct.update.base-same-type]
+The expression following `..` (the base) must have the same struct type as the new struct type being formed.
+
+r[expr.struct.update.fields]
+The entire expression uses the given values for the fields that were specified and moves or copies the remaining fields from the base expression.
+
+r[expr.struct.update.visibility-constraint]
+As with all struct expressions, all of the fields of the struct must be [visible], even those not explicitly named.
+
+```rust
+# struct Point3d { x: i32, y: i32, z: i32 }
+let mut base = Point3d {x: 1, y: 2, z: 3};
+let y_ref = &mut base.y;
+Point3d {y: 0, z: 10, .. base}; // OK, only base.x is accessed
+drop(y_ref);
+```
+
+r[expr.struct.default]
+## Default field syntax
+
+r[expr.struct.default.intro]
+A struct expression that constructs a value of a struct type can terminate with the syntax `..` without a following expression to denote that unlisted fields should be set to their [default values].
+
+r[expr.struct.default.fields]
+All fields without defualt values must be listed in the expression.
+The entire expression uses the given values for the fields that were specified and initializes the remaining fields with their respective default values.
+
+r[expr.struct.default.visibility-constraint]
+As with all struct expressions, all of the fields of the struct must be [visible], even those not explicitly named.
+
+```rust
+struct Pet {
+    name: Option<String>,
+    age: i128 = 42,
+}
+
+let pet = Pet { name: None, .. };
+assert_eq!(valid.age, 42);
+```
+
 [_OuterAttribute_]: ../attributes.md
 [IDENTIFIER]: ../identifiers.md
 [TUPLE_INDEX]: ../tokens.md#tuple-index
@@ -158,3 +181,4 @@ let b = Gamma{};  // Exact same value as `a`.
 [union]: ../items/unions.md
 [visible]: ../visibility-and-privacy.md
 [scrutinee]: ../glossary.md#scrutinee
+[default values]: ../items/structs.md#default-field-values

Diff for: src/items/structs.md

@@ -28,7 +28,11 @@ r[items.struct.syntax]
 > _StructField_ :\
 > &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
 > &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
-> &nbsp;&nbsp; [IDENTIFIER] `:` [_Type_]
+> &nbsp;&nbsp; [IDENTIFIER] `:` [_Type_]\
+> &nbsp;&nbsp; _StructFieldDefault_<sup>?</sup>
+>
+> _StructFieldDefault_ :\
+> &nbsp;&nbsp; `=` [_Expression_]
 >
 > _TupleFields_ :\
 > &nbsp;&nbsp; _TupleField_ (`,` _TupleField_)<sup>\*</sup> `,`<sup>?</sup>
@@ -86,6 +90,52 @@ r[items.struct.layout]
 The precise memory layout of a struct is not specified. One can specify a
 particular layout using the [`repr` attribute].
 
+r[items.struct.default]
+## Default field values
+
+r[items.struct.default.intro]
+A field in a non-tuple struct can be assigned a default value, which can be used in a [struct expression] using the [default field syntax]:
+
+```rust
+struct Pet {
+    name: Option<String>,
+    age: i128 = 42,
+}
+
+let pet = Pet { name: None, .. };
+assert_eq!(valid.age, 42);
+```
+
+r[items.struct.default.const]
+A default field value must be a [constant expression]:
+
+```rust,compile_fail
+struct Pet {
+    name: Option<String>,
+    age: i128 = { println!("calculating age"); 42 },
+    // ERROR: cannot call non-const function `_print` in constants
+}
+```
+
+r[item.struct.default.derive]
+The [derive macro] for the [`Default`] trait will use default field values in the implementation:
+
+```rust
+#[derive(Default)]
+struct Pet {
+    name: Option<String>, // impl Default for Pet will use Default::default() for name
+    age: i128 = 42, // impl Default for Pet will use the literal 42 for age
+}
+
+let default = Pet::default();
+assert_eq!(default.name, None);
+assert_eq!(default.age, 42);
+```
+
+Any fields without a default field value must have an implementation of [`Default`],
+whose `default` method will be used for these fields instead.
+
+[_Expression_]: ../expressions.md
 [_GenericParams_]: generics.md
 [_OuterAttribute_]: ../attributes.md
 [_Type_]: ../types.md#type-expressions
@@ -95,6 +145,10 @@ particular layout using the [`repr` attribute].
 [IDENTIFIER]: ../identifiers.md
 [constant]: constant-items.md
 [struct type]: ../types/struct.md
+[struct expression]: ../expressions/struct-expr.md
 [tuple type]: ../types/tuple.md
 [type namespace]: ../names/namespaces.md
 [value namespace]: ../names/namespaces.md
+[constant expression]: ../const_eval.md
+[derive macro]: ../procedural-macros.md#derive-macros
+[default field syntax]: ../expressions/struct-expr.md#default-field-syntax