Fix baseline not applied in EncodeWithFormatter, long→int delta arithmetic, doc comment, add formatter-path integration tests

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/f4994093-4128-4101-b5df-f6a031463712

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

Author: Copilot

src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs

@@ -16,8 +16,8 @@ namespace PolylineAlgorithm.Abstraction;
 /// <remarks>
 /// <para>
 /// <b>Formatter-based use (no subclassing required):</b>
-/// Supply a <see cref="PolylineOptions{TPolyline, TCoordinate}"/> via the
-/// <see cref="AbstractPolylineDecoder{TPolyline, TCoordinate}(PolylineOptions{TPolyline, TCoordinate})"/>
+/// Supply a <see cref="PolylineOptions{TCoordinate, TPolyline}"/> via the
+/// <see cref="AbstractPolylineDecoder{TPolyline, TCoordinate}(PolylineOptions{TCoordinate, TPolyline})"/>
 /// constructor. The formatters handle all type-specific concerns; override nothing.
 /// </para>
 /// <para>

src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs

@@ -213,22 +213,26 @@ private TPolyline EncodeWithFormatter(ReadOnlySpan<TCoordinate> coordinates, Can
         Span<char> buffer = temp is null ? stackalloc char[length] : temp.AsSpan(0, length);
 
         int position = 0;
-        int[] previous = new int[width];
+        long[] previous = new long[width];
         long[] values = new long[width];
         string encodedResult;
 
+        for (int j = 0; j < width; j++) {
+            previous[j] = _valueFormatter.GetBaseline(j);
+        }
+
         try {
             for (var i = 0; i < coordinates.Length; i++) {
                 cancellationToken.ThrowIfCancellationRequested();
 
                 _valueFormatter.GetValues(coordinates[i], values.AsSpan());
 
                 for (int j = 0; j < width; j++) {
-                    int current = (int)values[j];
-                    int delta = current - previous[j];
+                    long current = values[j];
+                    long delta = current - previous[j];
                     previous[j] = current;
 
-                    if (!PolylineEncoding.TryWriteValue(delta, buffer, ref position)) {
+                    if (!PolylineEncoding.TryWriteValue((int)delta, buffer, ref position)) {
                         _logger.LogOperationFailedDebug(OperationName);
                         _logger.LogCannotWriteValueToBufferWarning(position, i);
                         ExceptionGuard.ThrowCouldNotWriteEncodedValueToBuffer();

src/PolylineAlgorithm/Abstraction/IPolylineValueFormatter.cs

@@ -52,4 +52,12 @@ public interface IPolylineValueFormatter<TValue> {
     /// the length of the span received in <see cref="CreateItem"/>.
     /// </summary>
     int Width { get; }
+
+    /// <summary>
+    /// Returns the baseline (epoch) for the column at <paramref name="index"/>, or <c>0</c> if none is configured.
+    /// The encoder subtracts this value from the first item's scaled column value to keep the initial delta small.
+    /// </summary>
+    /// <param name="index">The zero-based column index. Must be in the range <c>[0, <see cref="Width"/>)</c>.</param>
+    /// <returns>The baseline value, or <c>0</c> when no baseline has been defined for the column.</returns>
+    long GetBaseline(int index) => 0L;
 }

src/PolylineAlgorithm/PublicAPI.Unshipped.txt

@@ -9,6 +9,7 @@ PolylineAlgorithm.Abstraction.IPolylineFormatter<TPolyline>.Read(TPolyline polyl
 PolylineAlgorithm.Abstraction.IPolylineFormatter<TPolyline>.Write(System.ReadOnlyMemory<char> encoded) -> TPolyline
 PolylineAlgorithm.Abstraction.IPolylineValueFormatter<TValue>
 PolylineAlgorithm.Abstraction.IPolylineValueFormatter<TValue>.CreateItem(System.ReadOnlySpan<long> values) -> TValue
+PolylineAlgorithm.Abstraction.IPolylineValueFormatter<TValue>.GetBaseline(int index) -> long
 PolylineAlgorithm.Abstraction.IPolylineValueFormatter<TValue>.GetValues(TValue item, System.Span<long> values) -> void
 PolylineAlgorithm.Abstraction.IPolylineValueFormatter<TValue>.Width.get -> int
 PolylineAlgorithm.PolylineFormatter

tests/PolylineAlgorithm.Tests/Abstraction/AbstractPolylineDecoderTests.cs

@@ -9,6 +9,7 @@ namespace PolylineAlgorithm.Tests.Abstraction;
 using PolylineAlgorithm.Utility;
 using System;
 using System.Collections.Generic;
+using PolylineAlgorithm;
 
 /// <summary>
 /// Tests for <see cref="AbstractPolylineDecoder{TPolyline, TCoordinate}"/>.
@@ -141,4 +142,99 @@ public void Decode_With_Pre_Cancelled_Token_Throws_OperationCanceledException()
         // Act & Assert
         Assert.ThrowsExactly<OperationCanceledException>(() => decoder.Decode(polyline, cts.Token).ToList());
     }
+
+    // -------------------------------------------------------------------------
+    // Formatter-based path (PolylineOptions<TValue, TPolyline> constructor)
+    // -------------------------------------------------------------------------
+
+    /// <summary>
+    /// Tests that the PolylineOptions constructor with null throws <see cref="ArgumentNullException"/>.
+    /// </summary>
+    [TestMethod]
+    public void Constructor_With_Null_PolylineOptions_Throws_ArgumentNullException() {
+        // Act & Assert
+        ArgumentNullException ex = Assert.ThrowsExactly<ArgumentNullException>(
+            () => new AbstractPolylineDecoder<string, (double, double)>((PolylineOptions<(double, double), string>)null!));
+        Assert.AreEqual("options", ex.ParamName);
+    }
+
+    /// <summary>
+    /// Tests that the formatter-based decoder decodes the known polyline to the expected coordinates.
+    /// </summary>
+    [TestMethod]
+    public void Decode_FormatterPath_With_Known_Polyline_Returns_Expected_Coordinates() {
+        // Arrange
+        PolylineValueFormatter<(double Latitude, double Longitude)> valueFormatter =
+            FormatterBuilder<(double Latitude, double Longitude)>.Create()
+                .AddValue("lat", c => c.Latitude)
+                .AddValue("lon", c => c.Longitude)
+                .WithCreate(static values => (values[0] / 1e5, values[1] / 1e5))
+                .Build();
+
+        PolylineOptions<(double Latitude, double Longitude), string> options = new(
+            valueFormatter,
+            PolylineFormatter.ForString);
+
+        AbstractPolylineDecoder<string, (double Latitude, double Longitude)> decoder = new(options);
+
+        string polyline = StaticValueProvider.Valid.GetPolyline();
+        (double Latitude, double Longitude)[] expected = [.. StaticValueProvider.Valid.GetCoordinates()];
+
+        // Act
+        (double Latitude, double Longitude)[] result = [.. decoder.Decode(polyline)];
+
+        // Assert
+        Assert.AreEqual(expected.Length, result.Length);
+        for (int i = 0; i < expected.Length; i++) {
+            Assert.AreEqual(expected[i].Latitude, result[i].Latitude, 1e-5);
+            Assert.AreEqual(expected[i].Longitude, result[i].Longitude, 1e-5);
+        }
+    }
+
+    /// <summary>
+    /// Tests that the formatter-based decoder throws <see cref="ArgumentNullException"/> for a null polyline.
+    /// </summary>
+    [TestMethod]
+    public void Decode_FormatterPath_With_Null_Polyline_Throws_ArgumentNullException() {
+        // Arrange
+        PolylineValueFormatter<(double, double)> valueFormatter =
+            FormatterBuilder<(double, double)>.Create()
+                .AddValue("lat", c => c.Item1)
+                .AddValue("lon", c => c.Item2)
+                .WithCreate(static values => (values[0] / 1e5, values[1] / 1e5))
+                .Build();
+
+        AbstractPolylineDecoder<string, (double, double)> decoder = new(
+            new PolylineOptions<(double, double), string>(valueFormatter, PolylineFormatter.ForString));
+
+        // Act & Assert
+        ArgumentNullException ex = Assert.ThrowsExactly<ArgumentNullException>(
+            () => decoder.Decode(null!).ToList());
+        Assert.AreEqual("polyline", ex.ParamName);
+    }
+
+    /// <summary>
+    /// Tests that the formatter-based decoder with a pre-cancelled token throws <see cref="OperationCanceledException"/>.
+    /// </summary>
+    [TestMethod]
+    public void Decode_FormatterPath_With_Pre_Cancelled_Token_Throws_OperationCanceledException() {
+        // Arrange
+        PolylineValueFormatter<(double, double)> valueFormatter =
+            FormatterBuilder<(double, double)>.Create()
+                .AddValue("lat", c => c.Item1)
+                .AddValue("lon", c => c.Item2)
+                .WithCreate(static values => (values[0] / 1e5, values[1] / 1e5))
+                .Build();
+
+        AbstractPolylineDecoder<string, (double, double)> decoder = new(
+            new PolylineOptions<(double, double), string>(valueFormatter, PolylineFormatter.ForString));
+
+        string polyline = StaticValueProvider.Valid.GetPolyline();
+        using CancellationTokenSource cts = new();
+        cts.Cancel();
+
+        // Act & Assert
+        Assert.ThrowsExactly<OperationCanceledException>(
+            () => decoder.Decode(polyline, cts.Token).ToList());
+    }
 }

tests/PolylineAlgorithm.Tests/Abstraction/AbstractPolylineEncoderTests.cs

@@ -8,6 +8,7 @@ namespace PolylineAlgorithm.Tests.Abstraction;
 using PolylineAlgorithm.Abstraction;
 using PolylineAlgorithm.Utility;
 using System;
+using PolylineAlgorithm;
 
 /// <summary>
 /// Tests for <see cref="AbstractPolylineEncoder{TCoordinate, TPolyline}"/>.
@@ -149,4 +150,126 @@ public void Encode_With_Small_Stack_Alloc_Limit_Uses_Heap_Allocation_And_Produce
         // Assert
         Assert.AreEqual(expected, result);
     }
+
+    // -------------------------------------------------------------------------
+    // Formatter-based path (PolylineOptions<TValue, TPolyline> constructor)
+    // -------------------------------------------------------------------------
+
+    /// <summary>
+    /// Tests that the PolylineOptions constructor with null throws <see cref="ArgumentNullException"/>.
+    /// </summary>
+    [TestMethod]
+    public void Constructor_With_Null_PolylineOptions_Throws_ArgumentNullException() {
+        // Act & Assert
+        ArgumentNullException ex = Assert.ThrowsExactly<ArgumentNullException>(
+            () => new AbstractPolylineEncoder<(double, double), string>((PolylineOptions<(double, double), string>)null!));
+        Assert.AreEqual("options", ex.ParamName);
+    }
+
+    /// <summary>
+    /// Tests that the formatter-based encoder round-trips known coordinates through the polyline wire format.
+    /// </summary>
+    [TestMethod]
+    public void Encode_FormatterPath_With_Known_Coordinates_Returns_Expected_Polyline() {
+        // Arrange
+        PolylineValueFormatter<(double Latitude, double Longitude)> valueFormatter =
+            FormatterBuilder<(double Latitude, double Longitude)>.Create()
+                .AddValue("lat", c => c.Latitude)
+                .AddValue("lon", c => c.Longitude)
+                .Build();
+
+        PolylineOptions<(double Latitude, double Longitude), string> options = new(
+            valueFormatter,
+            PolylineFormatter.ForString);
+
+        AbstractPolylineEncoder<(double Latitude, double Longitude), string> encoder = new(options);
+
+        (double Latitude, double Longitude)[] coordinates = [.. StaticValueProvider.Valid.GetCoordinates()];
+        string expected = StaticValueProvider.Valid.GetPolyline();
+
+        // Act
+        string result = encoder.Encode(coordinates.AsSpan());
+
+        // Assert
+        Assert.AreEqual(expected, result);
+    }
+
+    /// <summary>
+    /// Tests that the formatter-based encoder respects a non-zero baseline by subtracting it
+    /// from the first item's scaled value, producing a smaller first delta.
+    /// </summary>
+    [TestMethod]
+    public void Encode_FormatterPath_With_Baseline_Produces_Correct_First_Delta() {
+        // Arrange: a single coordinate at (1.0, 2.0) with precision 5.
+        // Without baseline, scaled values are (100000, 200000).
+        // With baseline lat=100000, the first lat delta must be 0 (100000 - 100000).
+        PolylineValueFormatter<(double Lat, double Lon)> valueFormatter =
+            FormatterBuilder<(double Lat, double Lon)>.Create()
+                .AddValue("lat", c => c.Lat)
+                .SetBaseline(100000L)   // scaled value of 1.0 at precision 5
+                .AddValue("lon", c => c.Lon)
+                .Build();
+
+        PolylineOptions<(double Lat, double Lon), string> optionsWithBaseline = new(
+            valueFormatter,
+            PolylineFormatter.ForString);
+
+        PolylineValueFormatter<(double Lat, double Lon)> valueFormatterNoBaseline =
+            FormatterBuilder<(double Lat, double Lon)>.Create()
+                .AddValue("lat", c => c.Lat)
+                .AddValue("lon", c => c.Lon)
+                .Build();
+
+        PolylineOptions<(double Lat, double Lon), string> optionsNoBaseline = new(
+            valueFormatterNoBaseline,
+            PolylineFormatter.ForString);
+
+        AbstractPolylineEncoder<(double Lat, double Lon), string> encoderWithBaseline = new(optionsWithBaseline);
+        AbstractPolylineEncoder<(double Lat, double Lon), string> encoderNoBaseline = new(optionsNoBaseline);
+
+        (double, double)[] coordinates = [(1.0, 2.0)];
+
+        // Act
+        string resultWithBaseline = encoderWithBaseline.Encode(coordinates.AsSpan());
+        string resultNoBaseline = encoderNoBaseline.Encode(coordinates.AsSpan());
+
+        // Assert: baseline shifts the first delta so the results differ, and the baseline result
+        // encodes a smaller (zero) latitude delta.
+        Assert.AreNotEqual(resultNoBaseline, resultWithBaseline);
+    }
+
+    /// <summary>
+    /// Tests that the formatter-based encoder produces output that the formatter-based decoder can
+    /// reconstruct exactly (full round-trip).
+    /// </summary>
+    [TestMethod]
+    public void Encode_FormatterPath_RoundTrip_Produces_Original_Coordinates() {
+        // Arrange
+        PolylineValueFormatter<(double Latitude, double Longitude)> valueFormatter =
+            FormatterBuilder<(double Latitude, double Longitude)>.Create()
+                .AddValue("lat", c => c.Latitude)
+                .AddValue("lon", c => c.Longitude)
+                .WithCreate(static values => (values[0] / 1e5, values[1] / 1e5))
+                .Build();
+
+        PolylineOptions<(double Latitude, double Longitude), string> options = new(
+            valueFormatter,
+            PolylineFormatter.ForString);
+
+        AbstractPolylineEncoder<(double Latitude, double Longitude), string> encoder = new(options);
+        AbstractPolylineDecoder<string, (double Latitude, double Longitude)> decoder = new(options);
+
+        (double Latitude, double Longitude)[] original = [.. StaticValueProvider.Valid.GetCoordinates()];
+
+        // Act
+        string encoded = encoder.Encode(original.AsSpan());
+        (double Latitude, double Longitude)[] decoded = [.. decoder.Decode(encoded)];
+
+        // Assert
+        Assert.AreEqual(original.Length, decoded.Length);
+        for (int i = 0; i < original.Length; i++) {
+            Assert.AreEqual(original[i].Latitude, decoded[i].Latitude, 1e-5);
+            Assert.AreEqual(original[i].Longitude, decoded[i].Longitude, 1e-5);
+        }
+    }
 }