Expand README with usage in async/await context and cleanup (#118)

Author: nietras

README.md

@@ -312,6 +312,7 @@ public bool DisableQuotesParsing { get; init; } = false;
 /// state after unescaped cols before next col. This is for efficiency to
 /// avoid allocating secondary memory for unescaped columns. Header
 /// columns/names will also be unescaped.
+/// Requires <see cref="DisableQuotesParsing"/> to be false.
 /// </remarks>
 public bool Unescape { get; init; } = false;
 ```
@@ -1432,6 +1433,57 @@ foreach (var row in reader)
 CollectionAssert.AreEqual(expected, actual);
 ```
 
+### Example - Use Extension Method Enumerate within async/await Context
+Since `SepReader.Row` is a `ref struct` as covered above, one has to avoid
+referencing it directly in async context. This can be done in a number of ways,
+but one way is to use `Enumerate` extension method to parse/extract data from
+row like shown below.
+
+```csharp
+var text = """
+           C
+           1
+           2
+           """;
+
+using var reader = Sep.Reader().FromText(text);
+var squaredSum = 0;
+// Use Enumerate to avoid referencing SepReader.Row in async context
+foreach (var value in reader.Enumerate(row => row["C"].Parse<int>()))
+{
+    squaredSum += await Task.Run(() => value * value);
+}
+Assert.AreEqual(5, squaredSum);
+```
+
+### Example - Use Local Function within async/await Context
+Another way to avoid referencing `SepReader.Row` directly in async context is to
+use custom iterator via `yield return` to parse/extract data from row like shown
+below.
+
+```csharp
+var text = """
+           C
+           1
+           2
+           """;
+
+using var reader = Sep.Reader().FromText(text);
+var squaredSum = 0;
+// Use custom local function Enumerate to avoid referencing
+// SepReader.Row in async context
+foreach (var value in Enumerate(reader))
+{
+    squaredSum += await Task.Run(() => value * value);
+}
+Assert.AreEqual(5, squaredSum);
+
+static IEnumerable<int> Enumerate(SepReader reader)
+{
+    foreach (var r in reader) { yield return r["C"].Parse<int>(); }
+}
+```
+
 ## RFC-4180
 While the [RFC-4180](https://www.ietf.org/rfc/rfc4180.txt) requires `\r\n`
 (CR,LF) as line ending, the well-known line endings (`\r\n`, `\n` and `\r`) are

src/Sep.Test/PackageAssetsTest.cs

@@ -11,11 +11,11 @@ public class PackageAssetsTest
 {
     internal static IEnumerable<object[]> ToStrings =>
     [
-        new[]{ SepToString.Direct },
-        new[]{ SepToString.OnePool() },
-        new[]{ SepToString.PoolPerCol() },
-        new[]{ SepToString.PoolPerColThreadSafe() },
-        new[]{ SepToString.PoolPerColThreadSafeFixedCapacity() },
+        [SepToString.Direct],
+        [SepToString.OnePool()],
+        [SepToString.PoolPerCol()],
+        [SepToString.PoolPerColThreadSafe()],
+        [SepToString.PoolPerColThreadSafeFixedCapacity()],
     ];
 
     [DataTestMethod]

src/Sep.Test/ReadMeTest.cs

@@ -5,8 +5,12 @@
 using System.Linq;
 using System.Runtime.CompilerServices;
 using System.Text;
+using System.Threading.Tasks;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
+#if NET8_0
 using PublicApiGenerator;
+#endif
+#pragma warning disable CA2007 // Consider calling ConfigureAwait on the awaited task
 
 // Only parallize on class level to avoid multiple writes to README file
 [assembly: Parallelize(Workers = 0, Scope = ExecutionScope.ClassLevel)]
@@ -288,6 +292,50 @@ public void ReadMeTest_Example_CustomSep_DisableColCountCheck()
         foreach (var readRow in reader) { }
     }
 
+    [TestMethod]
+    public async Task ReadMeTest_Example_AsyncAwaitContext_Enumerate()
+    {
+        var text = """
+                   C
+                   1
+                   2
+                   """;
+
+        using var reader = Sep.Reader().FromText(text);
+        var squaredSum = 0;
+        // Use Enumerate to avoid referencing SepReader.Row in async context
+        foreach (var value in reader.Enumerate(row => row["C"].Parse<int>()))
+        {
+            squaredSum += await Task.Run(() => value * value);
+        }
+        Assert.AreEqual(5, squaredSum);
+    }
+
+    [TestMethod]
+    public async Task ReadMeTest_Example_AsyncAwaitContext_CustomIterator()
+    {
+        var text = """
+                   C
+                   1
+                   2
+                   """;
+
+        using var reader = Sep.Reader().FromText(text);
+        var squaredSum = 0;
+        // Use custom local function Enumerate to avoid referencing
+        // SepReader.Row in async context
+        foreach (var value in Enumerate(reader))
+        {
+            squaredSum += await Task.Run(() => value * value);
+        }
+        Assert.AreEqual(5, squaredSum);
+
+        static IEnumerable<int> Enumerate(SepReader reader)
+        {
+            foreach (var r in reader) { yield return r["C"].Parse<int>(); }
+        }
+    }
+
     [TestMethod]
     public void ReadMeTest_UpdateBenchmarksInMarkdown()
     {
@@ -361,6 +409,8 @@ public void ReadMeTest_UpdateExampleCodeInMarkdown()
             (nameof(ReadMeTest_EnumerateTrySelect) + "()", "With this the above custom `Enumerate`"),
             (nameof(ReadMeTest_Example_Copy_Rows) + "()", "### Example - Copy Rows"),
             (nameof(ReadMeTest_Example_Skip_Empty_Rows) + "()", "### Example - Skip Empty Rows"),
+            (nameof(ReadMeTest_Example_AsyncAwaitContext_Enumerate) + "()", "### Example - Use Extension Method Enumerate within async/await Context"),
+            (nameof(ReadMeTest_Example_AsyncAwaitContext_CustomIterator) + "()", "### Example - Use Local Function within async/await Context"),
         };
         readmeLines = UpdateReadme(testSourceLines, readmeLines, testBlocksToUpdate,
             sourceStartLineOffset: 2, "    }", sourceEndLineOffset: 0, sourceWhitespaceToRemove: 8);
@@ -385,6 +435,8 @@ public void ReadMeTest_UpdateExampleCodeInMarkdown()
         File.WriteAllText(readmeFilePath, newReadme, Encoding.UTF8);
     }
 
+    // Only update public API in README for .NET 8.0 to keep consistent
+#if NET8_0
     [TestMethod]
     public void ReadMeTest_PublicApi()
     {
@@ -398,6 +450,7 @@ public void ReadMeTest_PublicApi()
         var newReadme = string.Join(Environment.NewLine, readmeLines) + Environment.NewLine;
         File.WriteAllText(readmeFilePath, newReadme, Encoding.UTF8);
     }
+#endif
 
     static string[] UpdateReadme(string[] sourceLines, string[] readmeLines,
         (string StartLineContains, string ReadmeLineBefore)[] blocksToUpdate,

src/Sep.Test/SepParserTest.cs

@@ -216,9 +216,9 @@ public void SepParserTest_ParseColEnds_Long_ColEndsAlmostFilled(object parserObj
 
         var expectedOutput = new ExpectedOutput([
           new(ColEnds: [0, 10, 46, 83], LineNumberTo: 4),
-          new(ColEnds: [83, 86], LineNumberTo: 5),
-          new(ColEnds: [87, 89, 101, 105, 107], LineNumberTo: 6),
-          new(ColEnds: [107, 111], LineNumberTo: 7),
+            new(ColEnds: [83, 86], LineNumberTo: 5),
+            new(ColEnds: [87, 89, 101, 105, 107], LineNumberTo: 6),
+            new(ColEnds: [107, 111], LineNumberTo: 7),
         ], new(ColEnds: [111], LineNumberTo: 7, CharsStartIndex: 112, ColEndsStartIndex: 13, ColCount: 0));
 
         AssertOutput(parser, charsStart, charsEnd, expectedOutput);

src/Sep.Test/SepReaderTest.cs

@@ -267,75 +267,75 @@ public void SepReaderTest_Info_Props()
 
     internal static IEnumerable<object[]> ColCountMismatchData =>
     [
-        [ """
-          C1;C2
-          123
-          """,
-          """
-          Found 1 column(s) on row 1/lines [2..3]:'123'
-          Expected 2 column(s) matching header/first row 'C1;C2'
-          """,
-          new [] { 2, 1 } ],
-        [ """
-          C1;C2
-          
-          1;2
-          """,
-          """
-          Found 1 column(s) on row 1/lines [2..3]:''
-          Expected 2 column(s) matching header/first row 'C1;C2'
-          """,
-          new [] { 2, 1, 2 } ],
-        [ """
-          C1;C2;C3
-          1;2;3
-          4;5
-          """,
-          """
-          Found 2 column(s) on row 2/lines [3..4]:'4;5'
-          Expected 3 column(s) matching header/first row 'C1;C2;C3'
-          """,
-          new [] { 3, 3, 2 } ],
-        [ """
-          C1;C2;C3
-          4;5
-          1;2;3
-          """,
-          """
-          Found 2 column(s) on row 1/lines [2..3]:'4;5'
-          Expected 3 column(s) matching header/first row 'C1;C2;C3'
-          """,
-          new [] { 3, 2, 3 } ],
-        [ """
-          C1
-          
-          4;5
-          """,
-          """
-          Found 2 column(s) on row 2/lines [3..4]:'4;5'
-          Expected 1 column(s) matching header/first row 'C1'
-          """,
-          new [] { 1, 1, 2 } ],
-        [ """
-          C1;C2
-          4;5
-          1;2;3
-          """,
-          """
-          Found 3 column(s) on row 2/lines [3..4]:'1;2;3'
-          Expected 2 column(s) matching header/first row 'C1;C2'
-          """,
-          new [] { 2, 2, 3 } ],
-        [ """
-          C1;C2
-          4";"5
-          1;2;345
-          """,
-          """
-          Found 1 column(s) on row 1/lines [2..3]:'4";"5'
-          Expected 2 column(s) matching header/first row 'C1;C2'
-          """,
-          new [] { 2, 1, 3 } ],
+        ["""
+         C1;C2
+         123
+         """,
+         """
+         Found 1 column(s) on row 1/lines [2..3]:'123'
+         Expected 2 column(s) matching header/first row 'C1;C2'
+         """,
+         new[] { 2, 1 }],
+        ["""
+         C1;C2
+         
+         1;2
+         """,
+         """
+         Found 1 column(s) on row 1/lines [2..3]:''
+         Expected 2 column(s) matching header/first row 'C1;C2'
+         """,
+         new[] { 2, 1, 2 }],
+        ["""
+         C1;C2;C3
+         1;2;3
+         4;5
+         """,
+         """
+         Found 2 column(s) on row 2/lines [3..4]:'4;5'
+         Expected 3 column(s) matching header/first row 'C1;C2;C3'
+         """,
+         new[] { 3, 3, 2 }],
+        ["""
+         C1;C2;C3
+         4;5
+         1;2;3
+         """,
+         """
+         Found 2 column(s) on row 1/lines [2..3]:'4;5'
+         Expected 3 column(s) matching header/first row 'C1;C2;C3'
+         """,
+         new[] { 3, 2, 3 }],
+        ["""
+         C1
+         
+         4;5
+         """,
+         """
+         Found 2 column(s) on row 2/lines [3..4]:'4;5'
+         Expected 1 column(s) matching header/first row 'C1'
+         """,
+         new[] { 1, 1, 2 }],
+        ["""
+         C1;C2
+         4;5
+         1;2;3
+         """,
+         """
+         Found 3 column(s) on row 2/lines [3..4]:'1;2;3'
+         Expected 2 column(s) matching header/first row 'C1;C2'
+         """,
+         new[] { 2, 2, 3 }],
+        ["""
+         C1;C2
+         4";"5
+         1;2;345
+         """,
+         """
+         Found 1 column(s) on row 1/lines [2..3]:'4";"5'
+         Expected 2 column(s) matching header/first row 'C1;C2'
+         """,
+         new[] { 2, 1, 3 }],
     ];
 
     [DataTestMethod]
@@ -412,28 +412,28 @@ public void SepReaderTest_ColumnCountMismatch_IgnoreThrows(
 
     internal static IEnumerable<object[]> LineNumbersData =>
     [
-        ["C1;C2\n123;456", new [] { (1, 2), (2, 3) }],
-        ["C1;C2\n123;456\n", new [] { (1, 2), (2, 3) }],
-        ["C1;C2\r\n123;456\r\n", new [] { (1, 2), (2, 3) }],
-        ["C1;C2\r123;456\r", new [] { (1, 2), (2, 3) }],
-        ["C1;C2\n123;456\n789;012\n", new [] { (1, 2), (2, 3), (3, 4) }],
+        ["C1;C2\n123;456", new[] { (1, 2), (2, 3) }],
+        ["C1;C2\n123;456\n", new[] { (1, 2), (2, 3) }],
+        ["C1;C2\r\n123;456\r\n", new[] { (1, 2), (2, 3) }],
+        ["C1;C2\r123;456\r", new[] { (1, 2), (2, 3) }],
+        ["C1;C2\n123;456\n789;012\n", new[] { (1, 2), (2, 3), (3, 4) }],
         // Line endings in quotes
-        [ """
-          "C1
-          ;
-          ";C2
-          "ab
-          ";"cd
-          ;
-          e"
-          "
-          
-          
-          
-          1";2
-          """, new [] { (1, 4), (4, 8), (8, 13) } ],
-        [ "\"C1\n\";C2\n\"1\n2\r3\";\"4\r\n56\"\n\"7\r\r\r\r\r89\";012\n",
-          new [] { (1, 3), (3, 7), (7, 13) } ],
+        ["""
+         "C1
+         ;
+         ";C2
+         "ab
+         ";"cd
+         ;
+         e"
+         "
+         
+         
+         
+         1";2
+         """, new[] { (1, 4), (4, 8), (8, 13) }],
+        ["\"C1\n\";C2\n\"1\n2\r3\";\"4\r\n56\"\n\"7\r\r\r\r\r89\";012\n",
+         new[] { (1, 3), (3, 7), (7, 13) }],
     ];
 
     [DataTestMethod]

src/Sep.Test/SepWriterColTest.cs

@@ -115,7 +115,7 @@ static void Run(SepWriter.ColAction action, string? expectedColValue = ColText,
         [
             () => Sep.Writer(o => o with { CultureInfo = cultureInfo ?? SepDefaults.CultureInfo }).ToText(),
             () => Sep.Default.Writer(o => o with { CultureInfo = cultureInfo ?? SepDefaults.CultureInfo }).ToText(),
-            () => new SepSpec(Sep.Default, cultureInfo ?? SepDefaults.CultureInfo).Writer(o => o with {  }).ToText(),
+            () => new SepSpec(Sep.Default, cultureInfo ?? SepDefaults.CultureInfo).Writer(o => o with { }).ToText(),
         ];
         foreach (var createWriter in createWriters)
         {

src/Sep/SepReaderOptions.cs

@@ -66,6 +66,7 @@ public SepReaderOptions(Sep? sep)
     /// state after unescaped cols before next col. This is for efficiency to
     /// avoid allocating secondary memory for unescaped columns. Header
     /// columns/names will also be unescaped.
+    /// Requires <see cref="DisableQuotesParsing"/> to be false.
     /// </remarks>
     public bool Unescape { get; init; } = false;
 }