feat: remove IPolylineWriter/IPolylineReader; restore stackalloc in encoder via ref struct PolylineWriter

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/8085d58f-4c97-4a7a-a577-f078ff234b2a

Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>

Author: Copilot

benchmarks/PolylineAlgorithm.Benchmarks/PolylineDecoderBenchmark.cs

@@ -8,6 +8,7 @@ namespace PolylineAlgorithm.Benchmarks;
 using BenchmarkDotNet.Attributes;
 using BenchmarkDotNet.Engines;
 using PolylineAlgorithm.Abstraction;
+using PolylineAlgorithm.Internal;
 using PolylineAlgorithm.Utility;
 
 /// <summary>
@@ -93,7 +94,7 @@ public void PolylineDecoder_Decode_Memory() {
     }
 
     private sealed class StringPolylineDecoder : AbstractPolylineDecoder<string, (double Latitude, double Longitude)> {
-        protected override (double Latitude, double Longitude) Read(IPolylineReader reader) =>
+        protected override (double Latitude, double Longitude) Read(PolylineReader reader) =>
             (reader.Read(), reader.Read());
 
         protected override ReadOnlyMemory<char> GetReadOnlyMemory(in string polyline) {
@@ -102,7 +103,7 @@ protected override ReadOnlyMemory<char> GetReadOnlyMemory(in string polyline) {
     }
 
     private sealed class CharArrayPolylineDecoder : AbstractPolylineDecoder<char[], (double Latitude, double Longitude)> {
-        protected override (double Latitude, double Longitude) Read(IPolylineReader reader) =>
+        protected override (double Latitude, double Longitude) Read(PolylineReader reader) =>
             (reader.Read(), reader.Read());
 
         protected override ReadOnlyMemory<char> GetReadOnlyMemory(in char[] polyline) {
@@ -111,7 +112,7 @@ protected override ReadOnlyMemory<char> GetReadOnlyMemory(in char[] polyline) {
     }
 
     private sealed class MemoryCharPolylineDecoder : AbstractPolylineDecoder<ReadOnlyMemory<char>, (double Latitude, double Longitude)> {
-        protected override (double Latitude, double Longitude) Read(IPolylineReader reader) =>
+        protected override (double Latitude, double Longitude) Read(PolylineReader reader) =>
             (reader.Read(), reader.Read());
 
         protected override ReadOnlyMemory<char> GetReadOnlyMemory(in ReadOnlyMemory<char> polyline) {

benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncoderBenchmark.cs

@@ -9,6 +9,7 @@ namespace PolylineAlgorithm.Benchmarks;
 using BenchmarkDotNet.Engines;
 using PolylineAlgorithm.Abstraction;
 using PolylineAlgorithm.Extensions;
+using PolylineAlgorithm.Internal;
 using PolylineAlgorithm.Utility;
 using System.Collections.Generic;
 
@@ -85,8 +86,8 @@ public void PolylineEncoder_Encode_List() {
     }
 
     private sealed class StringPolylineEncoder : AbstractPolylineEncoder<(double Latitude, double Longitude), string> {
-        protected override string CreatePolyline(ReadOnlyMemory<char> polyline) => polyline.ToString();
-        protected override void Write((double Latitude, double Longitude) item, IPolylineWriter writer) {
+        protected override string CreatePolyline(ReadOnlySpan<char> polyline) => polyline.ToString();
+        protected override void Write((double Latitude, double Longitude) item, ref PolylineWriter writer) {
             writer.Write(item.Latitude);
             writer.Write(item.Longitude);
         }

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs

@@ -7,6 +7,7 @@ namespace PolylineAlgorithm.NetTopologySuite.Sample;
 
 using global::NetTopologySuite.Geometries;
 using PolylineAlgorithm.Abstraction;
+using PolylineAlgorithm.Internal;
 using System;
 
 /// <summary>
@@ -27,7 +28,7 @@ protected override ReadOnlyMemory<char> GetReadOnlyMemory(in string polyline) {
     /// </summary>
     /// <param name="reader">The reader provided by the engine. Field 0 = latitude, field 1 = longitude.</param>
     /// <returns>Point instance.</returns>
-    protected override Point Read(IPolylineReader reader) {
+    protected override Point Read(PolylineReader reader) {
         double latitude = reader.Read();
         double longitude = reader.Read();
 

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs

@@ -7,18 +7,19 @@ namespace PolylineAlgorithm.NetTopologySuite.Sample;
 
 using global::NetTopologySuite.Geometries;
 using PolylineAlgorithm.Abstraction;
+using PolylineAlgorithm.Internal;
 using System;
 
 /// <summary>
 /// Polyline encoder using NetTopologySuite's Point type.
 /// </summary>
 internal sealed class NetTopologyPolylineEncoder : AbstractPolylineEncoder<Point, string> {
     /// <summary>
-    /// Creates encoded polyline string from memory.
+    /// Creates encoded polyline string from span.
     /// </summary>
-    /// <param name="polyline">Polyline memory.</param>
+    /// <param name="polyline">Polyline span.</param>
     /// <returns>Encoded polyline string.</returns>
-    protected override string CreatePolyline(ReadOnlyMemory<char> polyline) {
+    protected override string CreatePolyline(ReadOnlySpan<char> polyline) {
         if (polyline.IsEmpty) {
             return string.Empty;
         }
@@ -31,7 +32,7 @@ protected override string CreatePolyline(ReadOnlyMemory<char> polyline) {
     /// </summary>
     /// <param name="item">The point to write. Field 0 = latitude (Y), field 1 = longitude (X).</param>
     /// <param name="writer">The writer provided by the engine.</param>
-    protected override void Write(Point item, IPolylineWriter writer) {
+    protected override void Write(Point item, ref PolylineWriter writer) {
         ArgumentNullException.ThrowIfNull(item);
 
         // NetTopologySuite Point: Y = latitude, X = longitude

src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs

@@ -181,18 +181,18 @@ protected virtual void ValidateFormat(ReadOnlyMemory<char> sequence, ILogger? lo
     /// Reads field values from the polyline decoding pipeline and constructs one <typeparamref name="TCoordinate"/> item.
     /// </summary>
     /// <param name="reader">
-    /// The <see cref="IPolylineReader"/> cursor provided by the engine. Call <see cref="IPolylineReader.Read"/>
+    /// The <see cref="PolylineReader"/> cursor provided by the engine. Call <see cref="PolylineReader.Read"/>
     /// once for each expected field value, in the same order used by the corresponding encoder's
     /// <see cref="Write"/> override.
     /// </param>
     /// <returns>
     /// A <typeparamref name="TCoordinate"/> instance constructed from the decoded field values.
     /// </returns>
     /// <remarks>
-    /// Implementations must always call <see cref="IPolylineReader.Read"/> the same number of times,
+    /// Implementations must always call <see cref="PolylineReader.Read"/> the same number of times,
     /// in the same field order, for every item. The number of reads must match the number of writes
     /// performed by the corresponding encoder's <see cref="Write"/> override.
     /// </remarks>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    protected abstract TCoordinate Read(IPolylineReader reader);
+    protected abstract TCoordinate Read(PolylineReader reader);
 }

src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs

@@ -90,13 +90,12 @@ public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates, CancellationToken
         // Worst-case maximum: every value uses the maximum number of encoded characters.
         int maxCapacity = coordinates.Length * 2 * Defaults.Polyline.Block.Length.Max;
 
-        // Use ArrayPool for large buffers to avoid large heap allocations; for small buffers a fresh
-        // allocation is cheaper than pool overhead.
+        // Use stackalloc for small buffers (zero heap allocation); fall back to ArrayPool for large ones.
         const int StackAllocThreshold = 512;
-        char[]? rentedBuffer = maxCapacity > StackAllocThreshold
-            ? ArrayPool<char>.Shared.Rent(maxCapacity)
-            : null;
-        char[] buffer = rentedBuffer ?? new char[maxCapacity];
+        char[]? rentedBuffer = null;
+        Span<char> buffer = maxCapacity > StackAllocThreshold
+            ? (rentedBuffer = ArrayPool<char>.Shared.Rent(maxCapacity)).AsSpan(0, maxCapacity)
+            : stackalloc char[maxCapacity];
 
         PolylineWriter writer = new(buffer, Options.Precision);
 
@@ -107,10 +106,10 @@ public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates, CancellationToken
                 cancellationToken.ThrowIfCancellationRequested();
 
                 writer.BeginItem();
-                Write(coordinates[i], writer);
+                Write(coordinates[i], ref writer);
             }
 
-            result = CreatePolyline(writer.WrittenMemory);
+            result = CreatePolyline(writer.WrittenSpan);
         } finally {
             if (rentedBuffer is not null) {
                 ArrayPool<char>.Shared.Return(rentedBuffer);
@@ -136,29 +135,29 @@ static void ValidateEmptyCoordinates(ref ReadOnlySpan<TCoordinate> coordinates,
     }
 
     /// <summary>
-    /// Creates a polyline instance from the provided read-only sequence of characters.
+    /// Creates a polyline instance from the provided read-only span of characters.
     /// </summary>
-    /// <param name="polyline">A <see cref="ReadOnlyMemory{T}"/> containing the encoded polyline characters.</param>
+    /// <param name="polyline">A <see cref="ReadOnlySpan{T}"/> containing the encoded polyline characters.</param>
     /// <returns>
     /// An instance of <typeparamref name="TPolyline"/> representing the encoded polyline.
     /// </returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    protected abstract TPolyline CreatePolyline(ReadOnlyMemory<char> polyline);
+    protected abstract TPolyline CreatePolyline(ReadOnlySpan<char> polyline);
 
     /// <summary>
     /// Writes the field values of the specified item into the polyline encoding pipeline.
     /// </summary>
     /// <param name="item">The item whose field values are to be encoded.</param>
     /// <param name="writer">
-    /// The <see cref="IPolylineWriter"/> cursor provided by the engine. Call <see cref="IPolylineWriter.Write"/>
+    /// The <see cref="PolylineWriter"/> cursor provided by the engine. Call <see cref="PolylineWriter.Write"/>
     /// once for each field value, in a fixed, consistent order. The engine handles delta computation,
     /// zigzag encoding, and output buffering.
     /// </param>
     /// <remarks>
-    /// Implementations must always call <see cref="IPolylineWriter.Write"/> the same number of times,
+    /// Implementations must always call <see cref="PolylineWriter.Write"/> the same number of times,
     /// in the same field order, for every item. The corresponding <see cref="Read"/> override must
-    /// call <see cref="IPolylineReader.Read"/> the same number of times in the same order.
+    /// call <see cref="PolylineReader.Read"/> the same number of times in the same order.
     /// </remarks>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    protected abstract void Write(TCoordinate item, IPolylineWriter writer);
+    protected abstract void Write(TCoordinate item, ref PolylineWriter writer);
 }

src/PolylineAlgorithm/Abstraction/IPolylineReader.cs

@@ -5,7 +5,6 @@
 
 namespace PolylineAlgorithm.Internal;
 
-using PolylineAlgorithm.Abstraction;
 using PolylineAlgorithm.Internal.Diagnostics;
 using System.Runtime.CompilerServices;
 
@@ -18,7 +17,7 @@ namespace PolylineAlgorithm.Internal;
 /// The engine calls <see cref="BeginItem"/> before invoking the formatter for each item so that the
 /// slot index resets correctly while delta state is preserved across item boundaries.
 /// </remarks>
-internal sealed class PolylineReader : IPolylineReader {
+public sealed class PolylineReader {
     private readonly ReadOnlyMemory<char> _sequence;
     private int _position;
     private int[] _accumulated;

src/PolylineAlgorithm/Abstraction/IPolylineWriter.cs

@@ -5,7 +5,6 @@
 
 namespace PolylineAlgorithm.Internal;
 
-using PolylineAlgorithm.Abstraction;
 using PolylineAlgorithm.Internal.Diagnostics;
 using System;
 using System.Runtime.CompilerServices;
@@ -15,18 +14,19 @@ namespace PolylineAlgorithm.Internal;
 /// </summary>
 /// <remarks>
 /// Each instance wraps a caller-provided <see cref="char"/> buffer sized to the worst-case maximum
-/// capacity so that the buffer never needs to grow. The engine calls <see cref="BeginItem"/> before
+/// capacity so that the buffer never needs to grow. The buffer may be stack-allocated or rented from
+/// <see cref="System.Buffers.ArrayPool{T}"/>; the engine calls <see cref="BeginItem"/> before
 /// invoking the formatter for each item so that the slot index resets correctly while delta state is
 /// preserved across item boundaries.
 /// </remarks>
-internal sealed class PolylineWriter : IPolylineWriter {
-    private readonly char[] _buffer;
+public ref struct PolylineWriter {
+    private Span<char> _buffer;
     private int _position;
     private readonly uint _precision;
     private int[] _previous;
     private int _slotIndex;
 
-    internal PolylineWriter(char[] buffer, uint precision) {
+    internal PolylineWriter(Span<char> buffer, uint precision) {
         _buffer = buffer;
         _precision = precision;
         _previous = [];
@@ -48,7 +48,7 @@ public void Write(double value) {
         _previous[_slotIndex] = normalized;
         _slotIndex++;
 
-        if (!PolylineEncoding.TryWriteValue(delta, _buffer.AsSpan(), ref _position)) {
+        if (!PolylineEncoding.TryWriteValue(delta, _buffer, ref _position)) {
             ExceptionGuard.ThrowCouldNotWriteEncodedValueToBuffer();
         }
     }
@@ -67,7 +67,6 @@ public void Write(double value) {
 
     /// <summary>
     /// Returns the encoded polyline characters written so far.
-    /// The caller must not use this memory after the buffer is returned to <see cref="System.Buffers.ArrayPool{T}"/>.
     /// </summary>
-    internal ReadOnlyMemory<char> WrittenMemory => _buffer.AsMemory(0, _position);
+    internal ReadOnlySpan<char> WrittenSpan => _buffer[.._position];
 }