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

- AbstractPolylineEncoder: remove GetLatitude/GetLongitude, add ValuesPerItem + GetValues(item, Span<double>)
- AbstractPolylineDecoder: remove CreateCoordinate(lat, lon), add ValuesPerItem + CreateItem(ReadOnlyMemory<double>)
- CoordinateDelta: generalize from lat/lon pair to N-value array with Next(ReadOnlySpan<int>) and Deltas property
- LogDebugExtensions: rename LogDecodedCoordinateDebug → LogDecodedValuesDebug(count, position)
- Update all tests, samples, benchmarks, and utilities to new API
- Declare new protected abstract members in PublicAPI.Unshipped.txt

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/b28a38c3-82b5-4aea-87ac-240d0503f978

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

Author: Copilot

benchmarks/PolylineAlgorithm.Benchmarks/PolylineDecoderBenchmark.cs

@@ -93,8 +93,10 @@ public void PolylineDecoder_Decode_Memory() {
     }
 
     private sealed class StringPolylineDecoder : AbstractPolylineDecoder<string, (double Latitude, double Longitude)> {
-        protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude) {
-            return (latitude, 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 ReadOnlyMemory<char> GetReadOnlyMemory(in string polyline) {
@@ -103,8 +105,10 @@ protected override ReadOnlyMemory<char> GetReadOnlyMemory(in string polyline) {
     }
 
     private sealed class CharArrayPolylineDecoder : AbstractPolylineDecoder<char[], (double Latitude, double Longitude)> {
-        protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude) {
-            return (latitude, 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 ReadOnlyMemory<char> GetReadOnlyMemory(in char[] polyline) {
@@ -113,8 +117,10 @@ 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) CreateCoordinate(double latitude, double longitude) {
-            return (latitude, 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 ReadOnlyMemory<char> GetReadOnlyMemory(in ReadOnlyMemory<char> polyline) {

benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncoderBenchmark.cs

@@ -85,8 +85,11 @@ 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 double GetLatitude((double Latitude, double Longitude) current) => current.Latitude;
-        protected override double GetLongitude((double Latitude, double Longitude) current) => current.Longitude;
+        protected override void GetValues((double Latitude, double Longitude) item, Span<double> destination) {
+            destination[0] = item.Latitude;
+            destination[1] = item.Longitude;
+        }
     }
 }

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs

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

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs

@@ -7,11 +7,17 @@ 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>
@@ -26,26 +32,15 @@ protected override string CreatePolyline(ReadOnlyMemory<char> polyline) {
     }
 
     /// <summary>
-    /// Gets latitude from point.
+    /// Fills destination with latitude (index 0) and longitude (index 1) from the point.
     /// </summary>
-    /// <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;
+    /// <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;
     }
 }

src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs

@@ -6,19 +6,27 @@
 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 geographic coordinates.
+/// Provides a base implementation for decoding encoded polyline strings into sequences of items.
 /// </summary>
 /// <remarks>
-/// 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.
+/// 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>
 /// </remarks>
 /// <typeparam name="TPolyline">The type that represents the encoded polyline input.</typeparam>
-/// <typeparam name="TCoordinate">The type that represents a decoded geographic coordinate.</typeparam>
+/// <typeparam name="TCoordinate">The type that represents a decoded item.</typeparam>
 public abstract class AbstractPolylineDecoder<TPolyline, TCoordinate> : IPolylineDecoder<TPolyline, TCoordinate> {
     private readonly ILogger<AbstractPolylineDecoder<TPolyline, TCoordinate>> _logger;
 
@@ -53,6 +61,16 @@ 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.
@@ -64,7 +82,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 latitude and longitude pairs.
+    /// An <see cref="IEnumerable{T}"/> of <typeparamref name="TCoordinate"/> representing the decoded items.
     /// </returns>
     /// <exception cref="ArgumentNullException">
     /// Thrown when <paramref name="polyline"/> is <see langword="null"/>.
@@ -90,30 +108,45 @@ public IEnumerable<TCoordinate> Decode(TPolyline polyline, CancellationToken can
         ValidateSequence(sequence, _logger);
         ValidateFormat(sequence, _logger);
 
+        int valuesPerItem = ValuesPerItem;
         int position = 0;
-        int encodedLatitude = 0;
-        int encodedLongitude = 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;
+        }
 
         try {
             while (position < sequence.Length) {
                 cancellationToken.ThrowIfCancellationRequested();
 
-                if (!PolylineEncoding.TryReadValue(ref encodedLatitude, sequence, ref position)
-                    || !PolylineEncoding.TryReadValue(ref encodedLongitude, sequence, ref position)) {
+                bool allRead = true;
+                for (int j = 0; j < valuesPerItem; j++) {
+                    if (!PolylineEncoding.TryReadValue(ref runningRent[j], sequence, ref position)) {
+                        allRead = false;
+                        break;
+                    }
+                }
+
+                if (!allRead) {
                     _logger?.LogOperationFailedDebug(OperationName);
                     _logger?.LogInvalidPolylineWarning(position);
 
                     ExceptionGuard.ThrowInvalidPolylineFormat(position);
                 }
 
-                double decodedLatitude = PolylineEncoding.Denormalize(encodedLatitude, Options.Precision);
-                double decodedLongitude = PolylineEncoding.Denormalize(encodedLongitude, Options.Precision);
+                double[] decoded = new double[valuesPerItem];
+                for (int j = 0; j < valuesPerItem; j++) {
+                    decoded[j] = PolylineEncoding.Denormalize(runningRent[j], Options.Precision);
+                }
 
-                _logger?.LogDecodedCoordinateDebug(decodedLatitude, decodedLongitude, position);
+                _logger?.LogDecodedValuesDebug(valuesPerItem, position);
 
-                yield return CreateCoordinate(decodedLatitude, decodedLongitude);
+                yield return CreateItem(decoded.AsMemory());
             }
         } finally {
+            ArrayPool<int>.Shared.Return(runningRent!);
             _logger?.LogOperationFinishedDebug(OperationName);
         }
     }
@@ -188,17 +221,19 @@ 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 latitude and longitude values.
+    /// Creates a <typeparamref name="TCoordinate"/> instance from the specified decoded values.
     /// </summary>
-    /// <param name="latitude">
-    /// The latitude component of the coordinate, in degrees.
-    /// </param>
-    /// <param name="longitude">
-    /// The longitude component of the coordinate, in degrees.
+    /// <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>
     /// <returns>
-    /// A <typeparamref name="TCoordinate"/> instance representing the specified geographic coordinate.
+    /// A <typeparamref name="TCoordinate"/> instance representing the decoded item.
     /// </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 CreateCoordinate(double latitude, double longitude);
+    protected abstract TCoordinate CreateItem(ReadOnlyMemory<double> values);
 }