Remove restrictions on iterators

Remove or annotate any restrictions on iterator methods for `ref` and `unsafe` sections of the language reference.

Author: BillWagner

docs/csharp/language-reference/builtin-types/ref-struct.md

@@ -1,7 +1,7 @@
 ---
 title: "ref struct types"
 description: Learn about the ref struct type in C#
-ms.date: 10/12/2022
+ms.date: 06/28/2024
 ---
 # `ref` structure types (C# reference)
 
@@ -14,7 +14,7 @@ You can use the `ref` modifier in the declaration of a [structure type](struct.m
 - A `ref struct` can't be a type argument.
 - A `ref struct` variable can't be captured by a [lambda expression](../operators/lambda-expressions.md) or a [local function](../../programming-guide/classes-and-structs/local-functions.md).
 - A `ref struct` variable can't be used in an [`async`](../keywords/async.md) method. However, you can use `ref struct` variables in synchronous methods, for example, in methods that return <xref:System.Threading.Tasks.Task> or <xref:System.Threading.Tasks.Task%601>.
-- A `ref struct` variable can't be used in [iterators](../../iterators.md).
+- Prior to C# 13, a `ref struct` variable can't be used in [iterators](../../iterators.md). Beginning with C# 13, `ref struct` types and `ref` locals may be used in iterators, provided they are not in code segments with the `yield return` statement.
 
 You can define a disposable `ref struct`. To do that, ensure that a `ref struct` fits the [disposable pattern](~/_csharplang/proposals/csharp-8.0/using.md#pattern-based-using). That is, it has an instance `Dispose` method, which is accessible, parameterless and has a `void` return type. You can use the [using statement or declaration](../statements/using.md) with an instance of a disposable `ref struct`.
 

docs/csharp/language-reference/compiler-messages/cs4013.md

@@ -1,7 +1,7 @@
 ---
 description: "Compiler Error CS4013"
 title: "Compiler Error CS4013"
-ms.date: 9/12/2022
+ms.date: 06/28/2024
 f1_keywords:
   - "CS4013"
 helpviewer_keywords:
@@ -11,6 +11,8 @@ helpviewer_keywords:
 
 Instance of type cannot be used inside a nested function, query expression, iterator block or async method
 
+Beginning with C# 13, `ref struct` types can be used in iterator methods, provided that they are not in scope during a `yield return` statement.
+
 ## Example
 
  The following sample generates CS4013:
@@ -34,7 +36,7 @@ public class C
 }
 ```
 
-This enumerator method extracts lines of text from a character array.  It naively tries to use `ReadOnlySpan<T>` to improve performance.
+This enumerator method extracts lines of text from a character array.  It naively tries to use `ReadOnlySpan<T>` to improve performance. The preceding example exhibits the same error in C# 13, because the `ReadOnlySpan` instance `chars` is in scope at the `yield return` statement.
 
 ## To correct this error
 
@@ -75,3 +77,27 @@ To continue to use an iterator function, to correct this error, the method must
         yield return new string(chars, startIndex, chars.Length - startIndex);
     }
 ```
+
+In C# 13, a `ReadOnlySpan` can be used, but can only be used in code segments without a `yield return`:
+
+```csharp
+static IEnumerable<string> Lines2(char[] text)
+{
+    ReadOnlySpan<char> chars = text;
+
+    var lines = new List<string>();
+    var index = chars.IndexOf('\n');
+    while (index > 0)
+    {
+        lines.Add(chars[..index].ToString());
+        chars = chars[(index + 1)..];
+        index = chars.IndexOf('\n');
+    }
+
+    lines.Add(chars.ToString());
+    foreach(var line in lines)
+    {
+        yield return line;
+    }
+}
+```

docs/csharp/language-reference/compiler-messages/cs8176.md

@@ -1,7 +1,7 @@
 ---
 description: "Compiler Error CS8176"
 title: "Compiler Error CS8176"
-ms.date: 9/19/2022
+ms.date: 06/28/2024
 f1_keywords:
   - "CS8176"
 helpviewer_keywords:
@@ -13,6 +13,8 @@ Iterators cannot have by-reference locals
 
 Iterator blocks use deferred execution, where the evaluation of an expression is delayed until its realized value is actually required. To manage that deferred execution state, iterator blocks use a state machine, capturing variable state in closures implemented in compiler-generated classes and properties.  A local variable reference (on the stack) cannot be captured within the instance of a class in the heap, so the compiler issues an error.
 
+Beginning with C# 13, this restriction was removed.
+
 ## Example
 
  The following sample generates CS8176:

docs/csharp/language-reference/statements/yield.md

@@ -1,7 +1,7 @@
 ---
 title: "yield statement - provide the next element in an iterator"
 description: "Use the yield statement in iterators to provide the next value or signal the end of an iteration"
-ms.date: 11/22/2022
+ms.date: 06/28/2024
 f1_keywords: 
   - "yield"
   - "yield_CSharpKeyword"
@@ -37,7 +37,7 @@ You can't use the `yield` statements in:
 
 - methods with [in](../keywords/method-parameters.md#in-parameter-modifier), [ref](../keywords/ref.md), or [out](../keywords/method-parameters.md#out-parameter-modifier) parameters
 - [lambda expressions](../operators/lambda-expressions.md) and [anonymous methods](../operators/delegate-operator.md)
-- methods that contain [unsafe blocks](../keywords/unsafe.md)
+- [unsafe blocks](../keywords/unsafe.md). Prior to C# 13, `yield` was invalid in any method with an `unsafe` block. Beginning with C# 13, you can use `yield` in methods with `unsafe` blocks, but not in the `unsafe` block.
 
 ## Execution of an iterator
 

docs/csharp/misc/cs1629.md

@@ -1,7 +1,7 @@
 ---
 description: "Compiler Error CS1629"
 title: "Compiler Error CS1629"
-ms.date: 07/20/2015
+ms.date: 06/28/2024
 f1_keywords: 
   - "CS1629"
 helpviewer_keywords: 
@@ -11,6 +11,8 @@ ms.assetid: 907eae46-0265-4cd0-b27b-ff555d004259
 # Compiler Error CS1629
 
 Unsafe code may not appear in iterators  
+
+This restriction is relaxed in C# 13. You can use `unsafe` blocks, but the `yield return` statement can't be used in an `unsafe` block.
 
  The C# language specification does not allow unsafe code in iterators.