[create-pull-request] automated change (#1346)

Co-authored-by: BillWagner <[email protected]>

Author: github-actions[bot]

standard/README.md

@@ -472,6 +472,9 @@
     - [§13.9.3](statements.md#1393-the-do-statement)  The do statement
     - [§13.9.4](statements.md#1394-the-for-statement)  The for statement
     - [§13.9.5](statements.md#1395-the-foreach-statement)  The foreach statement
+      - [§13.9.5.1](statements.md#13951-general)  General
+      - [§13.9.5.2](statements.md#13952-synchronous-foreach)  Synchronous foreach
+      - [§13.9.5.3](statements.md#13953-await-foreach)  await foreach
   - [§13.10](statements.md#1310-jump-statements)  Jump statements
     - [§13.10.1](statements.md#13101-general)  General
     - [§13.10.2](statements.md#13102-the-break-statement)  The break statement
@@ -605,24 +608,24 @@
     - [§15.11.5](classes.md#15115-default-constructors)  Default constructors
   - [§15.12](classes.md#1512-static-constructors)  Static constructors
   - [§15.13](classes.md#1513-finalizers)  Finalizers
-  - [§15.14](classes.md#1514-iterators)  Iterators
+  - [§15.14](classes.md#1514-async-functions)  Async Functions
     - [§15.14.1](classes.md#15141-general)  General
-    - [§15.14.2](classes.md#15142-enumerator-interfaces)  Enumerator interfaces
-    - [§15.14.3](classes.md#15143-enumerable-interfaces)  Enumerable interfaces
-    - [§15.14.4](classes.md#15144-yield-type)  Yield type
-    - [§15.14.5](classes.md#15145-enumerator-objects)  Enumerator objects
-      - [§15.14.5.1](classes.md#151451-general)  General
-      - [§15.14.5.2](classes.md#151452-the-movenext-method)  The MoveNext method
-      - [§15.14.5.3](classes.md#151453-the-current-property)  The Current property
-      - [§15.14.5.4](classes.md#151454-the-dispose-method)  The Dispose method
-    - [§15.14.6](classes.md#15146-enumerable-objects)  Enumerable objects
-      - [§15.14.6.1](classes.md#151461-general)  General
-      - [§15.14.6.2](classes.md#151462-the-getenumerator-method)  The GetEnumerator method
-  - [§15.15](classes.md#1515-async-functions)  Async Functions
+    - [§15.14.2](classes.md#15142-task-type-builder-pattern)  Task-type builder pattern
+    - [§15.14.3](classes.md#15143-evaluation-of-a-task-returning-async-function)  Evaluation of a task-returning async function
+    - [§15.14.4](classes.md#15144-evaluation-of-a-void-returning-async-function)  Evaluation of a void-returning async function
+  - [§15.15](classes.md#1515-synchronous-and-asynchronous-iterators)  Synchronous and asynchronous iterators
     - [§15.15.1](classes.md#15151-general)  General
-    - [§15.15.2](classes.md#15152-task-type-builder-pattern)  Task-type builder pattern
-    - [§15.15.3](classes.md#15153-evaluation-of-a-task-returning-async-function)  Evaluation of a task-returning async function
-    - [§15.15.4](classes.md#15154-evaluation-of-a-void-returning-async-function)  Evaluation of a void-returning async function
+    - [§15.15.2](classes.md#15152-enumerator-interfaces)  Enumerator interfaces
+    - [§15.15.3](classes.md#15153-enumerable-interfaces)  Enumerable interfaces
+    - [§15.15.4](classes.md#15154-yield-type)  Yield type
+    - [§15.15.5](classes.md#15155-enumerator-objects)  Enumerator objects
+      - [§15.15.5.1](classes.md#151551-general)  General
+      - [§15.15.5.2](classes.md#151552-advance-the-enumerator)  Advance the enumerator
+      - [§15.15.5.3](classes.md#151553-retrieve-the-current-value)  Retrieve the current value
+      - [§15.15.5.4](classes.md#151554-dispose-of-resources)  Dispose of resources
+    - [§15.15.6](classes.md#15156-enumerable-objects)  Enumerable objects
+      - [§15.15.6.1](classes.md#151561-general)  General
+      - [§15.15.6.2](classes.md#151562-the-getenumerator-or-getasyncenumerator-method)  The GetEnumerator or GetAsyncEnumerator method
 - [§16](structs.md#16-structs)  Structs
   - [§16.1](structs.md#161-general)  General
   - [§16.2](structs.md#162-struct-declarations)  Struct declarations

standard/attributes.md

@@ -775,7 +775,7 @@ If a program uses a type or member that is decorated with the `Obsolete` attribu
 
 ### 22.5.5 The AsyncMethodBuilder attribute
 
-This attribute is described in [§15.15.1](classes.md#15151-general).
+This attribute is described in [§15.14.1](classes.md#15141-general).
 
 ### 22.5.6 Caller-info attributes
 

standard/classes.md

@@ -760,9 +760,9 @@ Specifically, an anonymous function `F` is compatible with a delegate type `D`
 - If `F` does not contain an *anonymous_function_signature*, then `D` may have zero or more parameters of any type, as long as no parameter of `D` is an output parameter.
 - If `F` has an explicitly typed parameter list, each parameter in `D` has the same modifiers as the corresponding parameter in `F` and an identity conversion exists between the corresponding parameter in `F`.
 - If `F` has an implicitly typed parameter list, `D` has no reference or output parameters.
-- If the body of `F` is an expression, and *either* `D` has a void return type *or* `F` is async and `D` has a `«TaskType»` return type  ([§15.15.1](classes.md#15151-general)), then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid expression (w.r.t [§12](expressions.md#12-expressions)) that would be permitted as a *statement_expression* ([§13.7](statements.md#137-expression-statements)).
+- If the body of `F` is an expression, and *either* `D` has a void return type *or* `F` is async and `D` has a `«TaskType»` return type  ([§15.14.1](classes.md#15141-general)), then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid expression (w.r.t [§12](expressions.md#12-expressions)) that would be permitted as a *statement_expression* ([§13.7](statements.md#137-expression-statements)).
 - If the body of `F` is a block, and *either* `D` has a void return type *or* `F` is async and `D` has a `«TaskType»` return type , then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid block (w.r.t [§13.3](statements.md#133-blocks)) in which no `return` statement specifies an expression.
-- If the body of `F` is an expression, and *either* `F` is non-async and `D` has a non-`void` return type `T`, *or* `F` is async and `D` has a `«TaskType»<T>` return type ([§15.15.1](classes.md#15151-general)), then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid expression (w.r.t [§12](expressions.md#12-expressions)) that is implicitly convertible to `T`.
+- If the body of `F` is an expression, and *either* `F` is non-async and `D` has a non-`void` return type `T`, *or* `F` is async and `D` has a `«TaskType»<T>` return type ([§15.14.1](classes.md#15141-general)), then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid expression (w.r.t [§12](expressions.md#12-expressions)) that is implicitly convertible to `T`.
 - If the body of `F` is a block, and *either* `F` is non-async and `D` has a non-void return type `T`, *or* `F` is async and `D` has a `«TaskType»<T>` return type, then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid statement block (w.r.t [§13.3](statements.md#133-blocks)) with a non-reachable end point in which each return statement specifies an expression that is implicitly convertible to `T`.
 
 > *Example*: The following examples illustrate these rules:

standard/conversions.md

@@ -886,8 +886,8 @@ The ***inferred effective return type*** is determined as follows:
 
 The ***inferred return type*** is determined as follows:
 
-- If `F` is async and the body of `F` is either an expression classified as nothing ([§12.2](expressions.md#122-expression-classifications)), or a block where no `return` statements have expressions, the inferred return type is `«TaskType»` ([§15.15.1](classes.md#15151-general)).
-- If `F` is async and has an inferred effective return type `T`, the inferred return type is `«TaskType»<T>»`([§15.15.1](classes.md#15151-general)).
+- If `F` is async and the body of `F` is either an expression classified as nothing ([§12.2](expressions.md#122-expression-classifications)), or a block where no `return` statements have expressions, the inferred return type is `«TaskType»` ([§15.14.1](classes.md#15141-general)).
+- If `F` is async and has an inferred effective return type `T`, the inferred return type is `«TaskType»<T>»`([§15.14.1](classes.md#15141-general)).
 - If `F` is non-async and has an inferred effective return type `T`, the inferred return type is `T`.
 - Otherwise, a return type cannot be inferred for `F`.
 
@@ -1118,7 +1118,7 @@ Given an expression `E` and a type `T`, `E` ***exactly matches*** `T` if one of
 - `E` is an anonymous function, `T` is either a delegate type `D` or an expression tree type `Expression<D>` and one of the following holds:
   - An inferred return type `X` exists for `E` in the context of the parameter list of `D` ([§12.6.3.12](expressions.md#126312-fixing)), and an identity conversion exists from `X` to the return type of `D`
   - `E` is an `async` lambda with no return value, and `D` has a return type which is a non-generic `«TaskType»`
-  - Either `E` is non-async and `D` has a return type `Y` or `E` is async and `D` has a return type `«TaskType»<Y>`([§15.15.1](classes.md#15151-general)), and one of the following holds:
+  - Either `E` is non-async and `D` has a return type `Y` or `E` is async and `D` has a return type `«TaskType»<Y>`([§15.14.1](classes.md#15141-general)), and one of the following holds:
     - The body of `E` is an expression that exactly matches `Y`
     - The body of `E` is a block where every return statement returns an expression that exactly matches `Y`
 
@@ -1127,8 +1127,8 @@ Given an expression `E` and a type `T`, `E` ***exactly matches*** `T` if one of
 Given two types `T₁` and `T₂`, `T₁` is a ***better conversion target*** than `T₂` if one of the following holds:
 
 - An implicit conversion from `T₁` to `T₂` exists and no implicit conversion from `T₂` to `T₁` exists
-- `T₁` is `«TaskType»<S₁>`([§15.15.1](classes.md#15151-general)), `T₂` is `«TaskType»<S₂>`, and `S₁` is a better conversion target than `S₂`
-- `T₁` is `«TaskType»<S₁>`([§15.15.1](classes.md#15151-general)), `T₂` is `«TaskType»<S₂>`, and `T₁` is more specialized than `T₂`
+- `T₁` is `«TaskType»<S₁>`([§15.14.1](classes.md#15141-general)), `T₂` is `«TaskType»<S₂>`, and `S₁` is a better conversion target than `S₂`
+- `T₁` is `«TaskType»<S₁>`([§15.14.1](classes.md#15141-general)), `T₂` is `«TaskType»<S₂>`, and `T₁` is more specialized than `T₂`
 - `T₁` is `S₁` or `S₁?` where `S₁` is a signed integral type, and `T₂` is `S₂` or `S₂?` where `S₂` is an unsigned integral type. Specifically:
   - `S₁` is `sbyte` and `S₂` is `byte`, `ushort`, `uint`, or `ulong`
   - `S₁` is `short` and `S₂` is `ushort`, `uint`, or `ulong`
@@ -2347,7 +2347,7 @@ A *this_access* is permitted only in the *block* of an instance constructor, an
   - If the constructor declaration has no constructor initializer, the `this` variable behaves exactly the same as an output parameter of the struct type. In particular, this means that the variable shall be definitely assigned in every execution path of the instance constructor.
   - Otherwise, the `this` variable behaves exactly the same as a `ref` parameter of the struct type. In particular, this means that the variable is considered initially assigned.
 - When `this` is used in a *primary_expression* within an instance method or instance accessor of a struct, it is classified as a variable. The type of the variable is the instance type ([§15.3.2](classes.md#1532-the-instance-type)) of the struct within which the usage occurs.
-  - If the method or accessor is not an iterator ([§15.14](classes.md#1514-iterators)) or async function ([§15.15](classes.md#1515-async-functions)), the `this` variable represents the struct for which the method or accessor was invoked.
+  - If the method or accessor is not an iterator ([§15.15](classes.md#1515-synchronous-and-asynchronous-iterators)) or async function ([§15.14](classes.md#1514-async-functions)), the `this` variable represents the struct for which the method or accessor was invoked.
     - If the struct is a `readonly struct`, the `this` variable behaves exactly the same as an input parameter of the struct type
     - Otherwise the `this` variable behaves exactly the same as a `ref` parameter of the struct type
   - If the method or accessor is an iterator or async function, the `this` variable represents a *copy* of the struct for which the method or accessor was invoked, and behaves exactly the same as a *value* parameter of the struct type.
@@ -3655,7 +3655,7 @@ await_expression
     ;
 ```
 
-An *await_expression* is only allowed in the body of an async function ([§15.15](classes.md#1515-async-functions)). Within the nearest enclosing async function, an *await_expression* shall not occur in these places:
+An *await_expression* is only allowed in the body of an async function ([§15.14](classes.md#1514-async-functions)). Within the nearest enclosing async function, an *await_expression* shall not occur in these places:
 
 - Inside a nested (non-async) anonymous function
 - Inside the block of a *lock_statement*
@@ -3696,7 +3696,7 @@ At run-time, the expression `await t` is evaluated as follows:
 
 - An awaiter `a` is obtained by evaluating the expression `(t).GetAwaiter()`.
 - A `bool` `b` is obtained by evaluating the expression `(a).IsCompleted`.
-- If `b` is `false` then evaluation depends on whether `a` implements the interface `System.Runtime.CompilerServices.ICriticalNotifyCompletion` (hereafter known as `ICriticalNotifyCompletion` for brevity). This check is done at binding time; i.e., at run-time if `a` has the compile-time type `dynamic`, and at compile-time otherwise. Let `r` denote the resumption delegate ([§15.15](classes.md#1515-async-functions)):
+- If `b` is `false` then evaluation depends on whether `a` implements the interface `System.Runtime.CompilerServices.ICriticalNotifyCompletion` (hereafter known as `ICriticalNotifyCompletion` for brevity). This check is done at binding time; i.e., at run-time if `a` has the compile-time type `dynamic`, and at compile-time otherwise. Let `r` denote the resumption delegate ([§15.14](classes.md#1514-async-functions)):
   - If `a` does not implement `ICriticalNotifyCompletion`, then the expression
     `((a) as INotifyCompletion).OnCompleted(r)` is evaluated.
   - If `a` does implement `ICriticalNotifyCompletion`, then the expression
@@ -5094,7 +5094,7 @@ When recognising an *anonymous_function_body* if both the *null_conditional_invo
 
 The `=>` operator has the same precedence as assignment (`=`) and is right-associative.
 
-An anonymous function with the `async` modifier is an async function and follows the rules described in [§15.15](classes.md#1515-async-functions).
+An anonymous function with the `async` modifier is an async function and follows the rules described in [§15.14](classes.md#1514-async-functions).
 
 The parameters of an anonymous function in the form of a *lambda_expression* can be explicitly or implicitly typed. In an explicitly typed parameter list, the type of each parameter is explicitly stated. In an implicitly typed parameter list, the types of the parameters are inferred from the context in which the anonymous function occurs—specifically, when the anonymous function is converted to a compatible delegate type or expression tree type, that type provides the parameter types ([§10.7](conversions.md#107-anonymous-function-conversions)).
 

standard/expressions.md

@@ -1741,10 +1741,10 @@ statement_expression_list
     : statement_expression (',' statement_expression)*
     ;
 
-// Source: §13.9.5 The foreach statement
+// Source: §13.9.5.1 General
 foreach_statement
-    : 'foreach' '(' ref_kind? local_variable_type identifier 'in' 
-      expression ')' embedded_statement
+    : 'await'? 'foreach' '(' ref_kind? local_variable_type identifier
+      'in' expression ')' embedded_statement
     ;
 
 // Source: §13.10.1 General

standard/grammar.md

@@ -61,9 +61,9 @@ A conforming implementation is required to document its choice of behavior in ea
 1. The layout of arrays, except in an unsafe context ([§12.8.17.4](expressions.md#128174-array-creation-expressions)).
 1. Whether there is any way to execute the *block* of an anonymous function other than through evaluation and invocation of the *lambda_expression* or *anonymous_method-expression* ([§12.19.3](expressions.md#12193-anonymous-function-bodies)).
 1. The exact timing of static field initialization ([§15.5.6.2](classes.md#15562-static-field-initialization)).
-1. The result of invoking `MoveNext` when an enumerator object is running ([§15.14.5.2](classes.md#151452-the-movenext-method)).
-1. The result of accessing `Current` when an enumerator object is in the before, running, or after states ([§15.14.5.3](classes.md#151453-the-current-property)).
-1. The result of invoking `Dispose` when an enumerator object is in the running state ([§15.14.5.4](classes.md#151454-the-dispose-method)).
+1. The result of invoking `MoveNext` when an enumerator object is running ([§15.15.5.2](classes.md#151552-advance-the-enumerator)).
+1. The result of accessing `Current` when an enumerator object is in the before, running, or after states ([§15.15.5.3](classes.md#151553-retrieve-the-current-value)).
+1. The result of invoking `Dispose` when an enumerator object is in the running state ([§15.15.5.4](classes.md#151554-dispose-of-resources)).
 1. The attributes of a type declared in multiple parts are determined by combining, in an unspecified order, the attributes of each of its parts ([§22.3](attributes.md#223-attribute-specification)).
 1. The order in which members are packed into a struct ([§23.6.9](unsafe-code.md#2369-the-sizeof-operator)).
 1. An exception occurs during finalizer execution, and that exception is not caught ([§21.4](exceptions.md#214-how-exceptions-are-handled)).