Revert "refactor: replace fixed lat/lon pair contract with N-value GetValues/CreateItem/ValuesPerItem"

This reverts commit a94f7c7.

Author: petesramek

benchmarks/PolylineAlgorithm.Benchmarks/PolylineDecoderBenchmark.cs

@@ -93,10 +93,8 @@ public void PolylineDecoder_Decode_Memory() {
     }
 
     private sealed class StringPolylineDecoder : AbstractPolylineDecoder<string, (double Latitude, double Longitude)> {
-        protected override int ValuesPerItem => 2;
-        protected override (double Latitude, double Longitude) CreateItem(ReadOnlyMemory<double> values) {
-            ReadOnlySpan<double> span = values.Span;
-            return (span[0], span[1]);
+        protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude) {
+            return (latitude, longitude);
         }
 
         protected override ReadOnlyMemory<char> GetReadOnlyMemory(in string polyline) {
@@ -105,10 +103,8 @@ protected override ReadOnlyMemory<char> GetReadOnlyMemory(in string polyline) {
     }
 
     private sealed class CharArrayPolylineDecoder : AbstractPolylineDecoder<char[], (double Latitude, double Longitude)> {
-        protected override int ValuesPerItem => 2;
-        protected override (double Latitude, double Longitude) CreateItem(ReadOnlyMemory<double> values) {
-            ReadOnlySpan<double> span = values.Span;
-            return (span[0], span[1]);
+        protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude) {
+            return (latitude, longitude);
         }
 
         protected override ReadOnlyMemory<char> GetReadOnlyMemory(in char[] polyline) {
@@ -117,10 +113,8 @@ protected override ReadOnlyMemory<char> GetReadOnlyMemory(in char[] polyline) {
     }
 
     private sealed class MemoryCharPolylineDecoder : AbstractPolylineDecoder<ReadOnlyMemory<char>, (double Latitude, double Longitude)> {
-        protected override int ValuesPerItem => 2;
-        protected override (double Latitude, double Longitude) CreateItem(ReadOnlyMemory<double> values) {
-            ReadOnlySpan<double> span = values.Span;
-            return (span[0], span[1]);
+        protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude) {
+            return (latitude, longitude);
         }
 
         protected override ReadOnlyMemory<char> GetReadOnlyMemory(in ReadOnlyMemory<char> polyline) {

benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncoderBenchmark.cs

@@ -85,11 +85,8 @@ public void PolylineEncoder_Encode_List() {
     }
 
     private sealed class StringPolylineEncoder : AbstractPolylineEncoder<(double Latitude, double Longitude), string> {
-        protected override int ValuesPerItem => 2;
         protected override string CreatePolyline(ReadOnlyMemory<char> polyline) => polyline.ToString();
-        protected override void GetValues((double Latitude, double Longitude) item, Span<double> destination) {
-            destination[0] = item.Latitude;
-            destination[1] = item.Longitude;
-        }
+        protected override double GetLatitude((double Latitude, double Longitude) current) => current.Latitude;
+        protected override double GetLongitude((double Latitude, double Longitude) current) => current.Longitude;
     }
 }

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs

@@ -14,21 +14,14 @@ namespace PolylineAlgorithm.NetTopologySuite.Sample;
 /// </summary>
 internal sealed class NetTopologyPolylineDecoder : AbstractPolylineDecoder<string, Point> {
     /// <summary>
-    /// Gets the number of encoded values per item: latitude (index 0) and longitude (index 1).
+    /// Creates a NetTopologySuite point from latitude and longitude.
     /// </summary>
-    protected override int ValuesPerItem => 2;
-
-    /// <summary>
-    /// Creates a NetTopologySuite point from the decoded values.
-    /// </summary>
-    /// <param name="values">
-    /// A memory region containing two values: index 0 is latitude, index 1 is longitude.
-    /// </param>
+    /// <param name="latitude">Latitude value.</param>
+    /// <param name="longitude">Longitude value.</param>
     /// <returns>Point instance.</returns>
-    protected override Point CreateItem(ReadOnlyMemory<double> values) {
-        ReadOnlySpan<double> span = values.Span;
+    protected override Point CreateCoordinate(double latitude, double longitude) {
         // NetTopologySuite Point: x = longitude, y = latitude
-        return new Point(span[1], span[0]);
+        return new Point(longitude, latitude);
     }
 
     /// <summary>

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs

@@ -7,17 +7,11 @@ namespace PolylineAlgorithm.NetTopologySuite.Sample;
 
 using global::NetTopologySuite.Geometries;
 using PolylineAlgorithm.Abstraction;
-using System;
 
 /// <summary>
 /// Polyline encoder using NetTopologySuite's Point type.
 /// </summary>
 internal sealed class NetTopologyPolylineEncoder : AbstractPolylineEncoder<Point, string> {
-    /// <summary>
-    /// Gets the number of values per item: latitude (index 0) and longitude (index 1).
-    /// </summary>
-    protected override int ValuesPerItem => 2;
-
     /// <summary>
     /// Creates encoded polyline string from memory.
     /// </summary>
@@ -32,15 +26,26 @@ protected override string CreatePolyline(ReadOnlyMemory<char> polyline) {
     }
 
     /// <summary>
-    /// Fills destination with latitude (index 0) and longitude (index 1) from the point.
+    /// Gets latitude from point.
     /// </summary>
-    /// <param name="item">Point instance.</param>
-    /// <param name="destination">Span of length 2 to fill.</param>
-    protected override void GetValues(Point item, Span<double> destination) {
-        ArgumentNullException.ThrowIfNull(item);
-
-        // NetTopologySuite Point: Y = latitude, X = longitude
-        destination[0] = item.Y;
-        destination[1] = item.X;
+    /// <param name="current">Point instance.</param>
+    /// <returns>Latitude value.</returns>
+    protected override double GetLatitude(Point current) {
+        ArgumentNullException.ThrowIfNull(current);
+
+        // NetTopologySuite Point: Y = latitude
+        return current.Y;
+    }
+
+    /// <summary>
+    /// Gets longitude from point.
+    /// </summary>
+    /// <param name="current">Point instance.</param>
+    /// <returns>Longitude value.</returns>
+    protected override double GetLongitude(Point current) {
+        ArgumentNullException.ThrowIfNull(current);
+
+        // NetTopologySuite Point: X = longitude
+        return current.X;
     }
 }

src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs

@@ -6,27 +6,19 @@
 using Microsoft.Extensions.Logging;
 using PolylineAlgorithm.Internal;
 using PolylineAlgorithm.Internal.Diagnostics;
-using System.Buffers;
 using System.Runtime.CompilerServices;
 
 namespace PolylineAlgorithm.Abstraction;
 
 /// <summary>
-/// Provides a base implementation for decoding encoded polyline strings into sequences of items.
+/// Provides a base implementation for decoding encoded polyline strings into sequences of geographic coordinates.
 /// </summary>
 /// <remarks>
-/// Derive from this class to implement a decoder for a specific polyline type. Override
-/// <see cref="ValuesPerItem"/>, <see cref="GetReadOnlyMemory"/>, and <see cref="CreateItem"/> to provide
-/// type-specific behavior.
-/// <para>
-/// The polyline format encodes each item as a fixed-length run of <see cref="ValuesPerItem"/> delta-compressed
-/// values. All items in a single polyline must have the same number of values. For example, a 2D GPS decoder
-/// sets <see cref="ValuesPerItem"/> to 2 (latitude, longitude), while a 3D GPS decoder sets it to 3
-/// (latitude, longitude, altitude).
-/// </para>
+/// Derive from this class to implement a decoder for a specific polyline type. Override <see cref="GetReadOnlyMemory"/>
+/// and <see cref="CreateCoordinate"/> to provide type-specific behavior.
 /// </remarks>
 /// <typeparam name="TPolyline">The type that represents the encoded polyline input.</typeparam>
-/// <typeparam name="TCoordinate">The type that represents a decoded item.</typeparam>
+/// <typeparam name="TCoordinate">The type that represents a decoded geographic coordinate.</typeparam>
 public abstract class AbstractPolylineDecoder<TPolyline, TCoordinate> : IPolylineDecoder<TPolyline, TCoordinate> {
     private readonly ILogger<AbstractPolylineDecoder<TPolyline, TCoordinate>> _logger;
 
@@ -61,16 +53,6 @@ protected AbstractPolylineDecoder(PolylineEncodingOptions options) {
     /// </summary>
     public PolylineEncodingOptions Options { get; }
 
-    /// <summary>
-    /// Gets the number of encoded values that make up a single decoded item.
-    /// </summary>
-    /// <remarks>
-    /// Override this property to specify the arity of each item. For example, return <c>2</c> for
-    /// latitude/longitude pairs, <c>3</c> for latitude/longitude/altitude triples, or any other count
-    /// that matches the encoding scheme used to produce the polyline.
-    /// </remarks>
-    protected abstract int ValuesPerItem { get; }
-
     /// <summary>
     /// Decodes an encoded <typeparamref name="TPolyline"/> into a sequence of <typeparamref name="TCoordinate"/> instances,
     /// with support for cancellation.
@@ -82,7 +64,7 @@ protected AbstractPolylineDecoder(PolylineEncodingOptions options) {
     /// A <see cref="CancellationToken"/> that can be used to cancel the decoding operation.
     /// </param>
     /// <returns>
-    /// An <see cref="IEnumerable{T}"/> of <typeparamref name="TCoordinate"/> representing the decoded items.
+    /// An <see cref="IEnumerable{T}"/> of <typeparamref name="TCoordinate"/> representing the decoded latitude and longitude pairs.
     /// </returns>
     /// <exception cref="ArgumentNullException">
     /// Thrown when <paramref name="polyline"/> is <see langword="null"/>.
@@ -108,45 +90,30 @@ public IEnumerable<TCoordinate> Decode(TPolyline polyline, CancellationToken can
         ValidateSequence(sequence, _logger);
         ValidateFormat(sequence, _logger);
 
-        int valuesPerItem = ValuesPerItem;
         int position = 0;
-
-        int[]? runningRent = ArrayPool<int>.Shared.Rent(valuesPerItem);
-        // Zero-initialize so delta decoding starts from 0 for all dimensions.
-        for (int j = 0; j < valuesPerItem; j++) {
-            runningRent[j] = 0;
-        }
+        int encodedLatitude = 0;
+        int encodedLongitude = 0;
 
         try {
             while (position < sequence.Length) {
                 cancellationToken.ThrowIfCancellationRequested();
 
-                bool allRead = true;
-                for (int j = 0; j < valuesPerItem; j++) {
-                    if (!PolylineEncoding.TryReadValue(ref runningRent[j], sequence, ref position)) {
-                        allRead = false;
-                        break;
-                    }
-                }
-
-                if (!allRead) {
+                if (!PolylineEncoding.TryReadValue(ref encodedLatitude, sequence, ref position)
+                    || !PolylineEncoding.TryReadValue(ref encodedLongitude, sequence, ref position)) {
                     _logger?.LogOperationFailedDebug(OperationName);
                     _logger?.LogInvalidPolylineWarning(position);
 
                     ExceptionGuard.ThrowInvalidPolylineFormat(position);
                 }
 
-                double[] decoded = new double[valuesPerItem];
-                for (int j = 0; j < valuesPerItem; j++) {
-                    decoded[j] = PolylineEncoding.Denormalize(runningRent[j], Options.Precision);
-                }
+                double decodedLatitude = PolylineEncoding.Denormalize(encodedLatitude, Options.Precision);
+                double decodedLongitude = PolylineEncoding.Denormalize(encodedLongitude, Options.Precision);
 
-                _logger?.LogDecodedValuesDebug(valuesPerItem, position);
+                _logger?.LogDecodedCoordinateDebug(decodedLatitude, decodedLongitude, position);
 
-                yield return CreateItem(decoded.AsMemory());
+                yield return CreateCoordinate(decodedLatitude, decodedLongitude);
             }
         } finally {
-            ArrayPool<int>.Shared.Return(runningRent!);
             _logger?.LogOperationFinishedDebug(OperationName);
         }
     }
@@ -221,19 +188,17 @@ protected virtual void ValidateFormat(ReadOnlyMemory<char> sequence, ILogger? lo
     protected abstract ReadOnlyMemory<char> GetReadOnlyMemory(in TPolyline polyline);
 
     /// <summary>
-    /// Creates a <typeparamref name="TCoordinate"/> instance from the specified decoded values.
+    /// Creates a <typeparamref name="TCoordinate"/> instance from the specified latitude and longitude values.
     /// </summary>
-    /// <param name="values">
-    /// A <see cref="ReadOnlyMemory{T}"/> of <see cref="double"/> containing exactly <see cref="ValuesPerItem"/>
-    /// decoded values for this item, in the same order they were encoded.
+    /// <param name="latitude">
+    /// The latitude component of the coordinate, in degrees.
+    /// </param>
+    /// <param name="longitude">
+    /// The longitude component of the coordinate, in degrees.
     /// </param>
     /// <returns>
-    /// A <typeparamref name="TCoordinate"/> instance representing the decoded item.
+    /// A <typeparamref name="TCoordinate"/> instance representing the specified geographic coordinate.
     /// </returns>
-    /// <remarks>
-    /// Implementations should read all required values from <paramref name="values"/> and construct the
-    /// <typeparamref name="TCoordinate"/> immediately. The memory is valid only for the duration of this call.
-    /// </remarks>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    protected abstract TCoordinate CreateItem(ReadOnlyMemory<double> values);
+    protected abstract TCoordinate CreateCoordinate(double latitude, double longitude);
 }