Merge branch 'draft-v9' into merge-updates

Author: BillWagner

.github/workflows/do-not-merge-label-check.yml

@@ -22,7 +22,7 @@ jobs:
         - 'do not merge'
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
         with:
           egress-policy: audit
 

standard/README.md

@@ -673,6 +673,8 @@
     - [§16.2.5](structs.md#1625-struct-interfaces)  Struct interfaces
     - [§16.2.6](structs.md#1626-struct-body)  Struct body
   - [§16.3](structs.md#163-struct-members)  Struct members
+    - [§16.3.1](structs.md#1631-general)  General
+    - [§16.3.2](structs.md#1632-readonly-members)  Readonly members
   - [§16.4](structs.md#164-class-and-struct-differences)  Class and struct differences
     - [§16.4.1](structs.md#1641-general)  General
     - [§16.4.2](structs.md#1642-value-semantics)  Value semantics

standard/classes.md

@@ -2143,7 +2143,7 @@ ref_method_modifier
     | 'override'
     | 'abstract'
     | 'extern'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     | unsafe_modifier   // unsafe code support
     ;
 
@@ -3398,7 +3398,7 @@ property_modifier
     | 'override'
     | 'abstract'
     | 'extern'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     | unsafe_modifier   // unsafe code support
     ;
     
@@ -3492,7 +3492,7 @@ accessor_modifier
     | 'internal' 'protected'
     | 'protected' 'private'
     | 'private' 'protected'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     ;
 
 accessor_body
@@ -4397,7 +4397,7 @@ event_modifier
     | 'override'
     | 'abstract'
     | 'extern'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     | unsafe_modifier   // unsafe code support
     ;
 
@@ -4678,7 +4678,7 @@ indexer_modifier
     | 'override'
     | 'abstract'
     | 'extern'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     | unsafe_modifier   // unsafe code support
     ;
 

standard/conversions.md

@@ -732,24 +732,99 @@ A user-defined explicit conversion from an expression `E` to a type `T` is pro
 - Find the set of types, `D`, from which user-defined conversion operators will be considered. This set consists of `S₀` (if `S₀` exists and is a class or struct), the base classes of `S₀` (if `S₀` exists and is a class), `T₀` (if `T₀` is a class or struct), and the base classes of `T₀` (if `T₀` is a class). A type is added to the set `D` only if an identity conversion to another type already included in the set doesn’t exist.
 - Find the set of applicable user-defined and lifted conversion operators, `U`. This set consists of the user-defined and lifted implicit or explicit conversion operators declared by the classes or structs in `D` that convert from a type encompassing `E` or encompassed by `S` (if it exists) to a type encompassing or encompassed by `T`. If `U` is empty, the conversion is undefined and a compile-time error occurs.
 - Find the most-specific source type, `Sₓ`, of the operators in `U`:
-  - If S exists and any of the operators in `U` convert from `S`, then `Sₓ` is `S`.
+  - If `S` exists and any of the operators in `U` convert from `S`, then `Sₓ` is `S`.
   - Otherwise, if any of the operators in `U` convert from types that encompass `E`, then `Sₓ` is the most-encompassed type in the combined set of source types of those operators. If no most-encompassed type can be found, then the conversion is ambiguous and a compile-time error occurs.
   - Otherwise, `Sₓ` is the most-encompassing type in the combined set of source types of the operators in `U`. If exactly one most-encompassing type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
 - Find the most-specific target type, `Tₓ`, of the operators in `U`:
   - If any of the operators in `U` convert to `T`, then `Tₓ` is `T`.
   - Otherwise, if any of the operators in `U` convert to types that are encompassed by `T`, then `Tₓ` is the most-encompassing type in the combined set of target types of those operators. If exactly one most-encompassing type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
   - Otherwise, `Tₓ` is the most-encompassed type in the combined set of target types of the operators in `U`. If no most-encompassed type can be found, then the conversion is ambiguous and a compile-time error occurs.
 - Find the most-specific conversion operator:
-  - If U contains exactly one user-defined conversion operator that converts from `Sₓ` to `Tₓ`, then this is the most-specific conversion operator.
+  - If `U` contains exactly one user-defined conversion operator that converts from `Sₓ` to `Tₓ`, then this is the most-specific conversion operator.
   - Otherwise, if `U` contains exactly one lifted conversion operator that converts from `Sₓ` to `Tₓ`, then this is the most-specific conversion operator.
   - Otherwise, the conversion is ambiguous and a compile-time error occurs.
-- Finally, apply the conversion:
-  - If `E` does not already have the type `Sₓ`, then a standard explicit conversion from E to `Sₓ` is performed.
-  - The most-specific user-defined conversion operator is invoked to convert from `Sₓ` to `Tₓ`.
-  - If `Tₓ` is not `T`, then a standard explicit conversion from `Tₓ` to `T` is performed.
+- Finally, determine the runtime conversions required, in order:
+  - If `E` does not already have the type `Sₓ`, then a standard explicit conversion from `E` to `Sₓ` is required.
+    - If this added standard explicit conversion is an explicit numeric ([§10.3.2](conversions.md#1032-explicit-numeric-conversions)) or enumeration ([§10.3.3](conversions.md#1033-explicit-enumeration-conversions)) one which may result in information loss ([§10.3.2](conversions.md#1032-explicit-numeric-conversions)), and the context is `unchecked` ([§12.8.20](expressions.md#12820-the-checked-and-unchecked-operators), [§13.12](statements.md#1312-the-checked-and-unchecked-statements)), then a compile-time warning shall be issued.<br>*Note*: In a `checked` context information loss would result in a runtime exception, hence no warning is required. If information loss is intended adding an explicit cast to the source will document this and silence the warning. *end note*
+  - The most-specific user-defined conversion operator is required to convert from `Sₓ` to `Tₓ`.
+  - If `Tₓ` is not `T`, then a standard explicit conversion from `Tₓ` to `T` is required.
 
 A user-defined explicit conversion from a type `S` to a type `T` exists if a user-defined explicit conversion exists from a variable of type `S` to `T`.
 
+> *Example*:
+>
+> The user-defined type `Dose` is used by the examples below.
+> Note that for doses greater than `MaxDosage` the user-defined type `LargeDose` is mentioned,
+> however it is not otherwise used and no source is given.
+>
+> ```csharp
+> public readonly struct Dose
+> {
+>     private readonly ushort dose;
+>
+>     public Dose(ushort dose)
+>     {
+>         const ushort MaxDosage = 1000; // mg
+>
+>         if (dose > MaxDosage)
+>         {
+>             throw new ArgumentOutOfRangeException
+>             (   $"Dosage too large (> {MaxDosage}mg)."
+>                 + " Consider LargeDose."
+>             );
+>         }
+>         this.dose = dose;
+>     }
+>
+>     public static explicit operator Dose(ushort b) => new Dose(b);
+>
+>     public override string ToString() => $"{dose}mg";
+>
+>     // other methods
+> }
+> ```
+>
+>
+> The following examples illustrate the above rules for explicit casting involving user-defined conversions:
+>
+> ```csharp
+> ushort amt0 = 500;          // ≤ MaxDosage
+> var dose0 = (Dose)amt0;     // amt0 is ushort, no additional conversions added
+> Console.WriteLine(dose0);   // outputs 500mg
+>
+> byte amt1 = 250;            // ≤ MaxDosage
+> var dose1 = (Dose)amt1;     // amt0 is byte, byte to ushort conversion added
+>                             // this does not risk information loss, no warning
+> Console.WriteLine(dose1);   // outputs 250mg
+>
+> var amt3 = 500;             // > MaxDosage, var types amt3 as int
+> var dose3 = (Dose)amt3;     // amt3 is int, int to ushort conversion added
+>                             // warning as information loss may occur
+> Console.WriteLine(dose3);   // outputs 500mg, no actual information loss
+>
+> ushort amt4 = 1500;         // > MaxDosage, requires LargeDose
+> var dose4 = (Dose)amt4;     // amt4 is ushort, no additional conversions added
+>                             // throws ArgumentOutOfRangeException
+>
+> var amt5 = 1500;            // > MaxDosage, var types amt5 as int
+> var dose5 = (Dose)amt5;     // amt5 is int, int to ushort conversion added
+>                             // warning as information loss may occur
+>                             // no actual information loss but out of range
+>                             // throws ArgumentOutOfRangeException
+>
+> var amt6 = 66036;           // var types amt6 as int
+> var dose6 = (Dose)amt6;     // amt3 is int, int to ushort conversion added
+>                             // warning as information loss may occur
+> Console.WriteLine(dose6);   // outputs 500mg, not 66036mg, due to information loss
+>
+> // Using a constructor instead of user-defined conversion:
+>
+> var dose7 = new Dose(amt6); // amt6 is int, constructor requires ushort
+>                             // compile time type error
+> ```
+>
+> *end example*
+
 ## 10.6 Conversions involving nullable types
 
 ### 10.6.1 Nullable Conversions

standard/grammar.md

@@ -2247,7 +2247,7 @@ ref_method_modifier
     | 'override'
     | 'abstract'
     | 'extern'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     | unsafe_modifier   // unsafe code support
     ;
 
@@ -2335,7 +2335,7 @@ property_modifier
     | 'override'
     | 'abstract'
     | 'extern'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     | unsafe_modifier   // unsafe code support
     ;
     
@@ -2381,7 +2381,7 @@ accessor_modifier
     | 'internal' 'protected'
     | 'protected' 'private'
     | 'private' 'protected'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     ;
 
 accessor_body
@@ -2419,7 +2419,7 @@ event_modifier
     | 'override'
     | 'abstract'
     | 'extern'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     | unsafe_modifier   // unsafe code support
     ;
 
@@ -2453,7 +2453,7 @@ indexer_modifier
     | 'override'
     | 'abstract'
     | 'extern'
-    | 'readonly'        // direct struct members only
+    | 'readonly'        // struct members only
     | unsafe_modifier   // unsafe code support
     ;
 
@@ -2617,7 +2617,7 @@ struct_body
     : '{' struct_member_declaration* '}'
     ;
 
-// Source: §16.3 Struct members
+// Source: §16.3.1 General
 struct_member_declaration
     : constant_declaration
     | field_declaration

standard/structs.md

@@ -114,6 +114,8 @@ struct_body
 
 ## 16.3 Struct members
 
+### 16.3.1 General
+
 The members of a struct consist of the members introduced by its *struct_member_declaration*s and the members inherited from the type `System.ValueType`.
 
 ```ANTLR
@@ -138,6 +140,46 @@ struct_member_declaration
 
 Except for the differences noted in [§16.4](structs.md#164-class-and-struct-differences), the descriptions of class members provided in [§15.3](classes.md#153-class-members) through [§15.12](classes.md#1512-static-constructors) apply to struct members as well.
 
+### 16.3.2 Readonly members
+
+An instance member definition or accessor of an instance property, indexer, or event that includes the `readonly` modifier has the following restrictions:
+
+- The `this` parameter is a `ref readonly` reference.
+- The member shall not reassign the value of `this` or an instance field of the receiver.
+- The member shall not reassign the value of an instance field-like event ([§15.8.2](classes.md#1582-field-like-events)) of the receiver.
+- If a readonly member invokes a non-readonly member, the structure referred to by `this` must be copied to use a writable reference for the `this` argument.
+
+> *Note:* Instance fields include the hidden backing field used for automatically implemented properties ([§15.7.4](classes.md#1574-automatically-implemented-properties)). *end note*
+<!-- markdownlint-disable MD028 -->
+
+<!-- markdownlint-enable MD028 -->
+> *Example*: A readonly member can modify the state of an object referred to by an instance field, even though the readonly member can’t reassign that instance member. The following code demonstrates the reassigning and modifying an instance field:
+>
+> <!-- Example: {template:"standalone-lib-without-using", name:"ReadonlyMember" } -->
+> ```csharp
+> public struct S
+> {
+>     private List<string> messages;
+>
+>     public S(IEnumerable<string> messages) =>
+>         this.messages = new List<string>(messages);
+>
+>     public void InitializeMessages() =>
+>         messages = new List<string>();
+>
+>     public readonly void AddMessage(string message)
+>     {
+>         if (messages == null)
+>         {
+>             throw new InvalidOperationException("Messages collection is not initialized.");
+>         }
+>         messages.Add(message);
+>     }
+> }
+> ```
+>
+> The `readonly` method `AddMessage` can change the state of a message list. The `InitializeMessages` member can clear and re-initialize the list of messages. In the case of `AddMessage`, the `readonly` modifier is valid. In the case of `InitializeMessages`, adding the `readonly` modifier is invalid. *end example*
+
 ## 16.4 Class and struct differences
 
 ### 16.4.1 General