Refactor project files and reader components for improved performance and code clarity

Author: GabrielMarquezMatte

Directory.Build.props

@@ -1,5 +1,9 @@
 <Project>
   <PropertyGroup>
+    <LangVersion>latest</LangVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <Deterministic>true</Deterministic>
     <AnalysisLevel>latest</AnalysisLevel>
     <AnalysisMode>All</AnalysisMode>
     <!-- <TreatWarningsAsErrors>true</TreatWarningsAsErrors> -->

src/ExcelReader.Core/ExcelReader.Core.csproj

@@ -2,9 +2,6 @@
 
   <PropertyGroup>
     <TargetFrameworks>net10.0;net8.0</TargetFrameworks>
-    <LangVersion>latest</LangVersion>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
 
     <!-- Ship XML docs (members without a doc comment do not warn). -->
@@ -35,7 +32,6 @@
     <DebugType>portable</DebugType>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <EmbedUntrackedSources>true</EmbedUntrackedSources>
-    <Deterministic>true</Deterministic>
     <ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
   </PropertyGroup>
 

src/ExcelReader.Core/Parser/Internal/ColumnParserFactory.cs

@@ -53,6 +53,8 @@ internal static class ColumnParserFactory
         [
             typeof(int), typeof(long), typeof(double), typeof(float), typeof(decimal),
             typeof(short), typeof(byte), typeof(uint), typeof(ulong), typeof(ushort),
+            // Guid is only reached here on net9+, where it implements IUtf8SpanParsable. On net8 the
+            // dedicated Guid build paths (guarded by #if NET8_0 below) intercept it before this set.
             typeof(Guid),
         ];
 

src/ExcelReader.Core/Reader/Excel.cs

@@ -181,7 +181,7 @@ private static IExcelRowReader OpenSeekable(Stream stream, bool leaveOpen, Excel
             }
             if (format is ExcelFileFormat.Unknown)
             {
-                throw UnknownFormat(stream, leaveOpen);
+                UnknownFormat(stream, leaveOpen);
             }
             return format switch
             {
@@ -207,7 +207,7 @@ private static async ValueTask<IExcelRowReader> OpenSeekableAsync(Stream stream,
             if (format is ExcelFileFormat.Unknown)
             {
                 await DisposeOnFailureAsync(stream, leaveOpen).ConfigureAwait(false);
-                throw new InvalidDataException("Unrecognized file format; expected an XLSX/XLSB (ZIP) or XLS (OLE2) workbook.");
+                UnknownFormatException();
             }
             return format switch
             {
@@ -235,10 +235,17 @@ private static ValueTask DisposeOnFailureAsync(Stream stream, bool leaveOpen)
             return leaveOpen ? ValueTask.CompletedTask : stream.DisposeAsync();
         }
 
-        private static InvalidDataException UnknownFormat(Stream stream, bool leaveOpen)
+        [DoesNotReturn]
+        private static void UnknownFormat(Stream stream, bool leaveOpen)
         {
             DisposeOnFailure(stream, leaveOpen);
-            return new InvalidDataException("Unrecognized file format; expected an XLSX/XLSB (ZIP) or XLS (OLE2) workbook.");
+            UnknownFormatException();
+        }
+
+        [DoesNotReturn]
+        private static void UnknownFormatException()
+        {
+            throw new InvalidDataException("Unrecognized file format; expected an XLSX/XLSB (ZIP) or XLS (OLE2) workbook.");
         }
 
         // Detection peeks the 8-byte signature then rewinds. For ZIP streams, opens a temporary

src/ExcelReader.Core/Reader/XlsReader.cs

@@ -317,27 +317,7 @@ private static void DecodeSharedStrings(ReadOnlySpan<byte> sst, ReadOnlySpan<int
                         pos += 4;
                     }
                     bool compressed = (flags & 1) == 0;
-                    int produced = 0;
-                    bool truncated = false;
-                    for (int c = 0; c < chars; c++)
-                    {
-                        // Drop boundaries already behind us (splits outside the character array), then
-                        // consume the grbit for a boundary that lands exactly on this character.
-                        while (boundaryIdx < boundaries.Length && boundaries[boundaryIdx] < pos) { boundaryIdx++; }
-                        if (boundaryIdx < boundaries.Length && boundaries[boundaryIdx] == pos)
-                        {
-                            if (pos >= sst.Length) { truncated = true; break; }
-                            compressed = (sst[pos] & 1) == 0;
-                            pos++;
-                            boundaryIdx++;
-                        }
-                        int step = compressed ? 1 : 2;
-                        if (pos + step > sst.Length) { truncated = true; break; }
-                        scratch[produced++] = compressed
-                            ? DecodeCp1252(sst[pos])
-                            : (char)(sst[pos] | (sst[pos + 1] << 8));
-                        pos += step;
-                    }
+                    int produced = DecodeChars(sst, boundaries, chars, scratch, ref pos, ref boundaryIdx, ref compressed, out bool truncated);
                     int maxBytes = System.Text.Encoding.UTF8.GetMaxByteCount(produced);
                     EnsureSharedCapacity(options, ref flat, flatLen + maxBytes);
                     flatLen += System.Text.Encoding.UTF8.GetBytes(scratch.AsSpan(0, produced), flat.AsSpan(flatLen));
@@ -360,6 +340,35 @@ private static void DecodeSharedStrings(ReadOnlySpan<byte> sst, ReadOnlySpan<int
             }
         }
 
+        // Decodes one shared string's code units into scratch, advancing the position and boundary
+        // index and flipping the compression mode at each grbit boundary. Returns the unit count
+        // produced, and reports truncated when the source ends mid-string.
+        private static int DecodeChars(ReadOnlySpan<byte> sst, ReadOnlySpan<int> boundaries, int chars, char[] scratch, ref int pos, ref int boundaryIdx, ref bool compressed, out bool truncated)
+        {
+            truncated = false;
+            int produced = 0;
+            for (int c = 0; c < chars; c++)
+            {
+                // Drop boundaries already behind us (splits outside the character array), then
+                // consume the grbit for a boundary that lands exactly on this character.
+                while (boundaryIdx < boundaries.Length && boundaries[boundaryIdx] < pos) { boundaryIdx++; }
+                if (boundaryIdx < boundaries.Length && boundaries[boundaryIdx] == pos)
+                {
+                    if (pos >= sst.Length) { truncated = true; break; }
+                    compressed = (sst[pos] & 1) == 0;
+                    pos++;
+                    boundaryIdx++;
+                }
+                int step = compressed ? 1 : 2;
+                if (pos + step > sst.Length) { truncated = true; break; }
+                scratch[produced++] = compressed
+                    ? DecodeCp1252(sst[pos])
+                    : (char)(sst[pos] | (sst[pos + 1] << 8));
+                pos += step;
+            }
+            return produced;
+        }
+
         private static void EnsureSharedCapacity(ExcelReaderOptions options, ref byte[] buffer, int needed)
         {
             if (needed <= buffer.Length)

src/ExcelReader.Core/Reader/XlsxReader.Enumerator.cs

@@ -136,12 +136,12 @@ public ValueTask<bool> MoveNextAsync()
                         case HeadKind.Row:
                             return ReadRowAsync();
                         default:
-                            ValueTask<bool> skipResult = SkipMarkupOrContinueAsync();
-                            if (skipResult.IsCompletedSuccessfully)
+                            ValueTask<bool>? skipResult = SkipMarkupOrContinue();
+                            if (skipResult is null)
                             {
-                                return new ValueTask<bool>(skipResult.Result);
+                                break; // markup skipped — continue scanning for the next element
                             }
-                            break;
+                            return skipResult.Value;
                     }
                 }
             }
@@ -178,7 +178,7 @@ private ValueTask<bool> ReadRowAsync()
                 Justification = "The .Result access is guarded by IsCompletedSuccessfully immediately above it — never blocks.")]
             [SuppressMessage("Reliability", "CA2012:Use ValueTasks correctly",
                 Justification = "The ValueTask is either returned through AwaitThenRestartAsync or consumed once after confirming synchronous completion.")]
-            private ValueTask<bool> SkipMarkupOrContinueAsync()
+            private ValueTask<bool>? SkipMarkupOrContinue()
             {
                 ValueTask<bool> skipTask = SkipMarkupAsync();
                 if (!skipTask.IsCompletedSuccessfully)
@@ -187,9 +187,9 @@ private ValueTask<bool> SkipMarkupOrContinueAsync()
                 }
                 if (skipTask.Result)
                 {
-                    return new ValueTask<bool>(true);
+                    return null; // markup skipped — caller continues the scan loop
                 }
-                return new ValueTask<bool>(false);
+                return new ValueTask<bool>(false); // end of sheetData/worksheet
             }
 
             // Safe for every pending step above except the row-buffered check below: none of them

src/ExcelReader.Core/Writer/CsvWriter.cs

@@ -119,8 +119,7 @@ public async ValueTask FlushAsync(CancellationToken ct = default)
             ct.ThrowIfCancellationRequested();
             if (_buffer.Length > 0)
             {
-                await _stream.WriteAsync(_buffer.Memory, ct).ConfigureAwait(false);
-                _buffer.Reset();
+                await FlushBufferAsync(ct).ConfigureAwait(false);
             }
             await _stream.FlushAsync(ct).ConfigureAwait(false);
         }

src/ExcelReader.Core/Writer/Internal/CellFormatter.cs

@@ -10,7 +10,7 @@ internal static class CellFormatter
         // The 5 XML entity chars, '_' (to detect literal "_xHHHH_" escape sequences that must be
         // themselves escaped), and every C0 control char that's illegal in XML 1.0 text content
         // (0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F — tab/LF/CR are legal and excluded).
-        private static readonly SearchValues<char> specialChars = SearchValues.Create(
+        private static readonly SearchValues<char> SpecialChars = SearchValues.Create(
             "&<>\"'_" +
             "\u0000\u0001\u0002\u0003\u0004\u0005\u0006\u0007\u0008\u000B\u000C" +
             "\u000E\u000F\u0010\u0011\u0012\u0013\u0014\u0015\u0016\u0017\u0018\u0019\u001A\u001B\u001C\u001D\u001E\u001F");
@@ -206,7 +206,7 @@ private static void ThrowIfNonFinite(double value)
         internal static void WriteEscaped(BiffBuffer xml, ReadOnlySpan<char> value)
         {
             int start = 0;
-            int next = value.IndexOfAny(specialChars);
+            int next = value.IndexOfAny(SpecialChars);
             while (next >= 0)
             {
                 int i = start + next;
@@ -238,7 +238,7 @@ internal static void WriteEscaped(BiffBuffer xml, ReadOnlySpan<char> value)
                     {
                         // A plain '_' remains in the pending run, but the next scan must move past
                         // it; otherwise this loop would rediscover the same underscore forever.
-                        int following = value[(i + 1)..].IndexOfAny(specialChars);
+                        int following = value[(i + 1)..].IndexOfAny(SpecialChars);
                         if (following < 0)
                         {
                             break;
@@ -258,7 +258,7 @@ internal static void WriteEscaped(BiffBuffer xml, ReadOnlySpan<char> value)
                     WriteHexEscape(xml, c);
                     start = i + 1;
                 }
-                next = value[start..].IndexOfAny(specialChars);
+                next = value[start..].IndexOfAny(SpecialChars);
             }
             if (start < value.Length)
             {

src/ExcelReader.Core/Writer/XlsbSheetWriter.cs

@@ -158,9 +158,6 @@ internal void WriteRecord(int id, ReadOnlySpan<byte> payload = default)
             MaybeFlush();
         }
 
-        // Fixed-length records (known-size cells, row headers) write header + fields straight into
-        // _records, skipping the Payload-buffer round trip that WriteRecord/Payload.Reset() needs for
-        // variable-length records.
         private void MaybeFlush()
         {
             if (_records.Length >= SpillThreshold)
@@ -239,6 +236,9 @@ private void BeginRow()
             _rowActive = true;
         }
 
+        // Fixed-length records (known-size cells, row headers) write header + fields straight into
+        // _records, skipping the Payload-buffer round trip that WriteRecord/Payload.Reset() needs for
+        // variable-length records.
         private void WriteRowHeader(int rowNumber)
         {
             const int Length = (6 * 4) + 1; // 6 x u32 + 1 byte

tests/ExcelReader.Benchmarks/ExcelReader.Benchmarks.csproj

@@ -3,8 +3,6 @@
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>net10.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
     <!-- Benchmark host app: ConfigureAwait is irrelevant (no captured sync context). -->
     <NoWarn>$(NoWarn);CA2007;MA0004</NoWarn>
   </PropertyGroup>