feat: add PolylineEncodingOptions/PolylineDecodingOptions with IChunkedPolylineEncoder/Decoder for chunked encoding support

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/49b11574-fbb3-42e8-b1f2-8af7fc403268

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

Author: Copilot

src/PolylineAlgorithm/Abstraction/IChunkedPolylineDecoder.cs

@@ -0,0 +1,52 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Abstraction;
+
+using System.Collections.Generic;
+using System.Threading;
+
+/// <summary>
+/// Provides per-call options-based chunked (stateless-continuation) decoding without inheriting the
+/// covariant <see cref="IPolylineDecoder{TPolyline, TValue}"/>. Implement both interfaces on the
+/// concrete decoder class to support both the standard and chunked overloads.
+/// </summary>
+/// <typeparam name="TPolyline">The encoded polyline type.</typeparam>
+/// <typeparam name="TValue">The coordinate type.</typeparam>
+/// <remarks>
+/// Use this interface when you need to decode a polyline that was produced by chunked encoding.
+/// Pass <see cref="PolylineDecodingOptions{TValue}.Previous"/> set to the last coordinate of the
+/// preceding decoded chunk to seed the accumulated-delta state correctly.
+/// </remarks>
+public interface IChunkedPolylineDecoder<TPolyline, TValue> {
+    /// <summary>
+    /// Decodes an encoded <typeparamref name="TPolyline"/> into a sequence of coordinates, applying
+    /// the per-call <paramref name="options"/> to control the accumulated-delta seed.
+    /// </summary>
+    /// <param name="polyline">The encoded polyline to decode. Must not be <see langword="null"/>.</param>
+    /// <param name="options">
+    /// Per-call options that control the starting accumulated-delta seed. Pass
+    /// <see langword="null"/> or an instance with <see cref="PolylineDecodingOptions{TValue}.Previous"/>
+    /// set to <see langword="null"/> to start from zero (the default behaviour).
+    /// </param>
+    /// <param name="cancellationToken">A token that can be used to cancel the operation.</param>
+    /// <returns>
+    /// An <see cref="IEnumerable{T}"/> of <typeparamref name="TValue"/> representing the decoded
+    /// coordinates.
+    /// </returns>
+    /// <exception cref="System.ArgumentNullException">
+    /// Thrown when <paramref name="polyline"/> is <see langword="null"/>.
+    /// </exception>
+    /// <exception cref="InvalidPolylineException">
+    /// Thrown when the polyline format is invalid or malformed.
+    /// </exception>
+    /// <exception cref="System.OperationCanceledException">
+    /// Thrown when <paramref name="cancellationToken"/> is canceled.
+    /// </exception>
+    IEnumerable<TValue> Decode(
+        TPolyline polyline,
+        PolylineDecodingOptions<TValue>? options,
+        CancellationToken cancellationToken);
+}

src/PolylineAlgorithm/Abstraction/IChunkedPolylineEncoder.cs

@@ -0,0 +1,47 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Abstraction;
+
+using System;
+using System.Collections.Generic;
+using System.Threading;
+
+/// <summary>
+/// Extends <see cref="IPolylineEncoder{TValue, TPolyline}"/> with a per-call options overload that
+/// supports chunked (stateless-continuation) encoding.
+/// </summary>
+/// <typeparam name="TValue">The coordinate type.</typeparam>
+/// <typeparam name="TPolyline">The encoded polyline type.</typeparam>
+/// <remarks>
+/// Use this interface when you need to encode a large coordinate sequence in independent chunks that
+/// can be concatenated into a single valid polyline. Pass
+/// <see cref="PolylineEncodingOptions{TValue}.Previous"/> set to the last coordinate of the
+/// preceding chunk to seed the delta baseline correctly.
+/// </remarks>
+public interface IChunkedPolylineEncoder<TValue, TPolyline> : IPolylineEncoder<TValue, TPolyline> {
+    /// <summary>
+    /// Encodes a sequence of geographic coordinates into an encoded polyline, applying the per-call
+    /// <paramref name="options"/> to control the delta baseline.
+    /// </summary>
+    /// <param name="coordinates">The collection of coordinates to encode.</param>
+    /// <param name="options">
+    /// Per-call options that control the starting delta baseline. Pass
+    /// <see langword="null"/> or an instance with <see cref="PolylineEncodingOptions{TValue}.Previous"/>
+    /// set to <see langword="null"/> to use the formatter's default baseline.
+    /// </param>
+    /// <param name="cancellationToken">A token that can be used to cancel the operation.</param>
+    /// <returns>
+    /// An instance of <typeparamref name="TPolyline"/> representing the encoded coordinates.
+    /// </returns>
+    /// <exception cref="System.ArgumentException">Thrown when <paramref name="coordinates"/> is empty.</exception>
+    /// <exception cref="System.OperationCanceledException">
+    /// Thrown when <paramref name="cancellationToken"/> is canceled.
+    /// </exception>
+    TPolyline Encode(
+        ReadOnlySpan<TValue> coordinates,
+        PolylineEncodingOptions<TValue>? options,
+        CancellationToken cancellationToken);
+}

src/PolylineAlgorithm/Extensions/PolylineDecoderExtensions.cs

@@ -97,4 +97,38 @@ public static IEnumerable<TValue> Decode<TValue>(this IPolylineDecoder<ReadOnlyM
 
         return decoder.Decode(polyline.AsMemory());
     }
+
+    /// <summary>
+    /// Decodes an encoded polyline string into a sequence of geographic coordinates, applying per-call
+    /// <paramref name="options"/> to seed the accumulated-delta state.
+    /// </summary>
+    /// <typeparam name="TValue">The coordinate type returned by the decoder.</typeparam>
+    /// <param name="decoder">The chunked decoder instance.</param>
+    /// <param name="polyline">The encoded polyline string to decode.</param>
+    /// <param name="options">
+    /// Per-call options that control the accumulated-delta seed. Pass <see langword="null"/> to start
+    /// from zero (the default behaviour).
+    /// </param>
+    /// <returns>
+    /// An <see cref="IEnumerable{T}"/> of <typeparamref name="TValue"/> containing the decoded
+    /// coordinate pairs.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="decoder"/> or <paramref name="polyline"/> is <see langword="null"/>.
+    /// </exception>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1062:Validate arguments of public methods", Justification = "Null is verified before use via ExceptionGuard.ThrowArgumentNull, which is annotated [DoesNotReturn]. CA1062 does not recognise custom [DoesNotReturn] helpers as null guards.")]
+    public static IEnumerable<TValue> Decode<TValue>(
+        this IChunkedPolylineDecoder<string, TValue> decoder,
+        string polyline,
+        PolylineDecodingOptions<TValue>? options) {
+        if (decoder is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(decoder));
+        }
+
+        if (polyline is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(polyline));
+        }
+
+        return decoder.Decode(polyline, options, CancellationToken.None);
+    }
 }

src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs

@@ -83,4 +83,78 @@ public static TPolyline Encode<TCoordinate, TPolyline>(this IPolylineEncoder<TCo
 
         return encoder.Encode(coordinates.AsSpan());
     }
+
+    /// <summary>
+    /// Encodes a <see cref="List{T}"/> of <typeparamref name="TCoordinate"/> instances into an encoded
+    /// polyline, applying per-call <paramref name="options"/> to control the delta baseline.
+    /// </summary>
+    /// <typeparam name="TCoordinate">The type that represents a geographic coordinate to encode.</typeparam>
+    /// <typeparam name="TPolyline">The type that represents the encoded polyline output.</typeparam>
+    /// <param name="encoder">The chunked encoder instance.</param>
+    /// <param name="coordinates">The list of coordinates to encode.</param>
+    /// <param name="options">
+    /// Per-call options that control the starting delta baseline. Pass <see langword="null"/> to use
+    /// the formatter's default baseline.
+    /// </param>
+    /// <returns>
+    /// A <typeparamref name="TPolyline"/> representing the encoded polyline.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="encoder"/> or <paramref name="coordinates"/> is <see langword="null"/>.
+    /// </exception>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1002:Do not expose generic lists", Justification = "We need a list as we do need to marshal it as span.")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "MA0016:Prefer using collection abstraction instead of implementation", Justification = "We need a list as we do need to marshal it as span.")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1062:Validate arguments of public methods", Justification = "Null is verified before use via ExceptionGuard.ThrowArgumentNull, which is annotated [DoesNotReturn]. CA1062 does not recognise custom [DoesNotReturn] helpers as null guards.")]
+    public static TPolyline Encode<TCoordinate, TPolyline>(
+        this IChunkedPolylineEncoder<TCoordinate, TPolyline> encoder,
+        List<TCoordinate> coordinates,
+        PolylineEncodingOptions<TCoordinate>? options) {
+        if (encoder is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(encoder));
+        }
+
+        if (coordinates is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(coordinates));
+        }
+
+#if NET5_0_OR_GREATER
+        return encoder.Encode(CollectionsMarshal.AsSpan(coordinates), options, CancellationToken.None);
+#else
+        return encoder.Encode([.. coordinates], options, CancellationToken.None);
+#endif
+    }
+
+    /// <summary>
+    /// Encodes an array of <typeparamref name="TCoordinate"/> instances into an encoded polyline,
+    /// applying per-call <paramref name="options"/> to control the delta baseline.
+    /// </summary>
+    /// <typeparam name="TCoordinate">The type that represents a geographic coordinate to encode.</typeparam>
+    /// <typeparam name="TPolyline">The type that represents the encoded polyline output.</typeparam>
+    /// <param name="encoder">The chunked encoder instance.</param>
+    /// <param name="coordinates">The array of coordinates to encode.</param>
+    /// <param name="options">
+    /// Per-call options that control the starting delta baseline. Pass <see langword="null"/> to use
+    /// the formatter's default baseline.
+    /// </param>
+    /// <returns>
+    /// A <typeparamref name="TPolyline"/> representing the encoded polyline.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="encoder"/> or <paramref name="coordinates"/> is <see langword="null"/>.
+    /// </exception>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1062:Validate arguments of public methods", Justification = "Null is verified before use via ExceptionGuard.ThrowArgumentNull, which is annotated [DoesNotReturn]. CA1062 does not recognise custom [DoesNotReturn] helpers as null guards.")]
+    public static TPolyline Encode<TCoordinate, TPolyline>(
+        this IChunkedPolylineEncoder<TCoordinate, TPolyline> encoder,
+        TCoordinate[] coordinates,
+        PolylineEncodingOptions<TCoordinate>? options) {
+        if (encoder is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(encoder));
+        }
+
+        if (coordinates is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(coordinates));
+        }
+
+        return encoder.Encode(coordinates.AsSpan(), options, CancellationToken.None);
+    }
 }

src/PolylineAlgorithm/PolylineDecoder.cs

@@ -24,7 +24,7 @@ namespace PolylineAlgorithm;
 /// <see cref="IPolylineFormatter{TCoordinate, TPolyline}"/> to the constructor. The formatter handles
 /// all type-specific concerns; no subclassing is required.
 /// </remarks>
-public class PolylineDecoder<TPolyline, TCoordinate> : IPolylineDecoder<TPolyline, TCoordinate> {
+public class PolylineDecoder<TPolyline, TCoordinate> : IPolylineDecoder<TPolyline, TCoordinate>, IChunkedPolylineDecoder<TPolyline, TCoordinate> {
     private readonly IPolylineFormatter<TCoordinate, TPolyline> _formatter;
     private readonly ILogger<PolylineDecoder<TPolyline, TCoordinate>> _logger;
 
@@ -114,4 +114,98 @@ public IEnumerable<TCoordinate> Decode(TPolyline polyline, CancellationToken can
             _logger.LogOperationFinishedDebug(OperationName);
         }
     }
+
+    /// <summary>
+    /// Decodes an encoded <typeparamref name="TPolyline"/> into a sequence of
+    /// <typeparamref name="TCoordinate"/> instances, applying per-call <paramref name="options"/> to
+    /// seed the accumulated-delta state. Use this overload to decode polylines that were produced by
+    /// chunked encoding.
+    /// </summary>
+    /// <param name="polyline">The encoded polyline to decode. Must not be <see langword="null"/>.</param>
+    /// <param name="options">
+    /// Per-call options that control the accumulated-delta seed. Pass <see langword="null"/> or an
+    /// instance with <see cref="PolylineDecodingOptions{TCoordinate}.Previous"/> set to
+    /// <see langword="null"/> to start from zero (same as calling
+    /// <see cref="Decode(TPolyline, CancellationToken)"/>).
+    /// </param>
+    /// <param name="cancellationToken">A token that can be used to cancel the operation.</param>
+    /// <returns>
+    /// An <see cref="IEnumerable{T}"/> of <typeparamref name="TCoordinate"/> representing the decoded
+    /// coordinates.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="polyline"/> is <see langword="null"/>.
+    /// </exception>
+    /// <exception cref="InvalidPolylineException">
+    /// Thrown when the polyline format is invalid or malformed.
+    /// </exception>
+    /// <exception cref="OperationCanceledException">
+    /// Thrown when <paramref name="cancellationToken"/> is canceled during decoding.
+    /// </exception>
+    public IEnumerable<TCoordinate> Decode(
+        TPolyline polyline,
+        PolylineDecodingOptions<TCoordinate>? options,
+        CancellationToken cancellationToken) {
+        const string OperationName = nameof(Decode);
+
+        _logger.LogOperationStartedDebug(OperationName);
+
+        if (polyline is null) {
+            _logger.LogNullArgumentWarning(nameof(polyline));
+            ExceptionGuard.ThrowArgumentNull(nameof(polyline));
+        }
+
+        ReadOnlyMemory<char> sequence = _formatter.Read(polyline);
+
+        if (sequence.Length < Defaults.Polyline.Block.Length.Min) {
+            _logger.LogOperationFailedDebug(OperationName);
+            _logger.LogPolylineCannotBeShorterThanWarning(sequence.Length, Defaults.Polyline.Block.Length.Min);
+            ExceptionGuard.ThrowInvalidPolylineLength(sequence.Length, Defaults.Polyline.Block.Length.Min);
+        }
+
+        try {
+            PolylineEncoding.ValidateFormat(sequence.Span);
+        } catch (ArgumentException ex) {
+            _logger.LogInvalidPolylineFormatWarning(ex);
+            throw;
+        }
+
+        int width = _formatter.Width;
+        long[] accumulated = new long[width];
+        int position = 0;
+
+        SeedAccumulated(accumulated, options);
+
+        try {
+            while (position < sequence.Length) {
+                cancellationToken.ThrowIfCancellationRequested();
+
+                for (int j = 0; j < width; j++) {
+                    if (!PolylineEncoding.TryReadValue(ref accumulated[j], sequence, ref position)) {
+                        _logger.LogOperationFailedDebug(OperationName);
+                        _logger.LogInvalidPolylineWarning(position);
+                        ExceptionGuard.ThrowInvalidPolylineFormat(position);
+                    }
+                }
+
+                yield return _formatter.CreateItem(accumulated.AsSpan());
+            }
+        } finally {
+            _logger.LogOperationFinishedDebug(OperationName);
+        }
+    }
+
+    private void SeedAccumulated(long[] accumulated, PolylineDecodingOptions<TCoordinate>? options) {
+        if (options is not { HasPrevious: true }) {
+            return;
+        }
+
+        int width = _formatter.Width;
+        long[] scaled = new long[width];
+        _formatter.GetValues(options.Previous, scaled.AsSpan());
+
+        for (int j = 0; j < width; j++) {
+            accumulated[j] = scaled[j] - _formatter.GetBaseline(j);
+        }
+    }
 }

src/PolylineAlgorithm/PolylineDecodingOptions.cs

@@ -0,0 +1,51 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm;
+
+/// <summary>
+/// Per-call options for a chunked decoding operation.
+/// </summary>
+/// <typeparam name="TCoordinate">The coordinate type understood by the formatter.</typeparam>
+/// <remarks>
+/// Pass an instance of this class to the chunked
+/// <see cref="Abstraction.IChunkedPolylineDecoder{TPolyline, TValue}.Decode"/> overload to control
+/// the accumulated-delta seed used at the start of each chunk. When <see cref="HasPrevious"/> is
+/// <see langword="false"/> zero-initialisation is used, which is the existing default behaviour.
+/// </remarks>
+public sealed class PolylineDecodingOptions<TCoordinate> {
+    private readonly TCoordinate _previous;
+
+    /// <summary>
+    /// Initializes a new instance of <see cref="PolylineDecodingOptions{TCoordinate}"/> with no
+    /// previous coordinate (zero-initialised baseline will be used).
+    /// </summary>
+    public PolylineDecodingOptions() { }
+
+    /// <summary>
+    /// Initializes a new instance of <see cref="PolylineDecodingOptions{TCoordinate}"/> with the
+    /// specified previous coordinate used to seed the accumulated-delta state.
+    /// </summary>
+    /// <param name="previous">
+    /// The last coordinate of the previous chunk, used to seed the accumulated-delta state.
+    /// </param>
+    public PolylineDecodingOptions(TCoordinate previous) {
+        _previous = previous;
+        HasPrevious = true;
+    }
+
+    /// <summary>
+    /// Gets a value indicating whether a previous coordinate has been supplied to seed the
+    /// accumulated-delta state. When <see langword="false"/> zero-initialisation is used, which is
+    /// the existing default.
+    /// </summary>
+    public bool HasPrevious { get; }
+
+    /// <summary>
+    /// Gets the last coordinate of the previous chunk, used to seed the accumulated-delta state.
+    /// Only meaningful when <see cref="HasPrevious"/> is <see langword="true"/>.
+    /// </summary>
+    public TCoordinate Previous => _previous;
+}