updates

Author: petesramek

benchmarks/PolylineAlgorithm.Benchmarks/PolylineDecoderBenchmark.cs

@@ -11,7 +11,7 @@ namespace PolylineAlgorithm.Benchmarks;
 using PolylineAlgorithm.Utility;
 
 /// <summary>
-/// Benchmarks for <see cref="PolylineDecoder{TPolyline, TCoordinate}"/>.
+/// Benchmarks for <see cref="PolylineDecoder{TPolyline, TValue}"/>.
 /// </summary>
 public class PolylineDecoderBenchmark {
     private readonly Consumer _consumer = new();
@@ -57,8 +57,8 @@ public class PolylineDecoderBenchmark {
         FormatterBuilder<(double Latitude, double Longitude), T>.Create()
             .AddValue("lat", static c => c.Latitude)
             .AddValue("lon", static c => c.Longitude)
-            .WithCreate(static v => (v[0], v[1]))
-            .ForPolyline(write, read)
+            .WithValueFactory(static v => (v[0], v[1]))
+            .WithReaderWriter(write, read)
             .Build();
 
     private static PolylineDecoder<string, (double Latitude, double Longitude)> CreateStringDecoder() {

benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncoderBenchmark.cs

@@ -3,12 +3,10 @@ namespace PolylineAlgorithm.Benchmarks;
 using BenchmarkDotNet.Attributes;
 using BenchmarkDotNet.Engines;
 using PolylineAlgorithm;
-using PolylineAlgorithm.Extensions;
 using PolylineAlgorithm.Utility;
-using System.Collections.Generic;
 
 /// <summary>
-/// Benchmarks for <see cref="PolylineEncoder{TCoordinate, TPolyline}"/>.
+/// Benchmarks for <see cref="PolylineEncoder{TValue, TPolyline}"/>.
 /// </summary>
 public class PolylineEncoderBenchmark {
     private readonly Consumer _consumer = new();
@@ -20,11 +18,6 @@ public class PolylineEncoderBenchmark {
     public int CoordinatesCount { get; set; }
 
 #pragma warning disable CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.
-    /// <summary>
-    /// Coordinates as list.
-    /// </summary>
-    public List<(double Latitude, double Longitude)> List { get; private set; }
-
     /// <summary>
     /// Coordinates as array.
     /// </summary>
@@ -47,7 +40,7 @@ public class PolylineEncoderBenchmark {
             FormatterBuilder<(double Latitude, double Longitude), string>.Create()
                 .AddValue("lat", static c => c.Latitude)
                 .AddValue("lon", static c => c.Longitude)
-                .ForPolyline(static m => new string(m.Span), static s => s.AsMemory())
+                .WithReaderWriter(static m => new string(m.Span), static s => s.AsMemory())
                 .Build();
 
         return new PolylineEncoder<(double Latitude, double Longitude), string>(
@@ -59,8 +52,7 @@ public class PolylineEncoderBenchmark {
     /// </summary>
     [GlobalSetup]
     public void SetupData() {
-        List = [.. RandomValueProvider.GetCoordinates(CoordinatesCount)];
-        Array = [.. List];
+        Array = [.. RandomValueProvider.GetCoordinates(CoordinatesCount)];
         Memory = Array.AsMemory();
     }
 
@@ -81,13 +73,4 @@ public void PolylineEncoder_Encode_Array() {
         var polyline = _encoder.Encode(Array);
         _consumer.Consume(polyline);
     }
-
-    /// <summary>
-    /// Benchmark: encode coordinates from list.
-    /// </summary>
-    [Benchmark]
-    public void PolylineEncoder_Encode_List() {
-        var polyline = _encoder.Encode(List);
-        _consumer.Consume(polyline);
-    }
 }

samples/PolylineAlgorithm.NetTopologySuite.Sample/Program.cs

@@ -15,8 +15,8 @@ public static void Main(string[] args) {
                 .AddValue("lat", static p => p.Y)
                 .AddValue("lon", static p => p.X)
                 // The formatter automatically denormalizes scaled values, so v[0] = latitude, v[1] = longitude.
-                .WithCreate(static v => new Point(x: v[1], y: v[0]))
-                .ForPolyline(
+                .WithValueFactory(static v => new Point(x: v[1], y: v[0]))
+                .WithReaderWriter(
                     static m => m.IsEmpty ? string.Empty : new string(m.Span),
                     static s => s.AsMemory())
                 .Build();

samples/PolylineAlgorithm.SensorData.Sample/Program.cs

@@ -21,10 +21,10 @@ public static void Main(string[] args) {
                 .SetBaseline(TimestampBaseEpoch)
                 .AddValue("temperature", static r => r.Temperature, precision: 5)
                 // The formatter automatically denormalizes: v[0] = Unix seconds, v[1] = temperature.
-                .WithCreate(static v => new SensorReading(
+                .WithValueFactory(static v => new SensorReading(
                     DateTimeOffset.FromUnixTimeSeconds((long)v[0]),
                     v[1]))
-                .ForPolyline(static m => new string(m.Span), static s => s.AsMemory())
+                .WithReaderWriter(static m => new string(m.Span), static s => s.AsMemory())
                 .Build();
 
         PolylineOptions<SensorReading, string> options = new(formatter);

src/PolylineAlgorithm/Abstraction/IChunkedPolylineDecoder.cs

@@ -19,7 +19,7 @@ namespace PolylineAlgorithm.Abstraction;
 /// The coordinate type returned by the decoder. Typical implementations return a struct or class that
 /// contains latitude and longitude (for example a <c>LatLng</c> type or a <c>ValueTuple&lt;double,double&gt;</c>).
 /// </typeparam>
-public interface IPolylineDecoder<TPolyline, out TValue> {
+public interface IPolylineDecoder<TPolyline, TValue> {
     /// <summary>
     /// Decodes the specified encoded polyline into an ordered sequence of geographic coordinates.
     /// The sequence preserves the original vertex order encoded by the <paramref name="polyline"/>.
@@ -45,5 +45,5 @@ public interface IPolylineDecoder<TPolyline, out TValue> {
     /// <exception cref="OperationCanceledException">
     /// Thrown when the provided <paramref name="cancellationToken"/> requests cancellation.
     /// </exception>
-    IEnumerable<TValue> Decode(TPolyline polyline, CancellationToken cancellationToken = default);
+    IEnumerable<TValue> Decode(TPolyline polyline, PolylineDecodingOptions<TValue>? options = null, CancellationToken cancellationToken = default);
 }

src/PolylineAlgorithm/Abstraction/IChunkedPolylineEncoder.cs

@@ -73,5 +73,5 @@ public interface IPolylineEncoder<TValue, TPolyline> {
     /// <exception cref="System.OperationCanceledException">
     /// Thrown if the operation is canceled via <paramref name="cancellationToken"/>.
     /// </exception>
-    TPolyline Encode(ReadOnlySpan<TValue> coordinates, CancellationToken cancellationToken = default);
+    TPolyline Encode(ReadOnlySpan<TValue> coordinates, PolylineEncodingOptions<TValue>? options = null, CancellationToken cancellationToken = default);
 }

src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs

@@ -8,19 +8,19 @@ namespace PolylineAlgorithm.Abstraction;
 using System;
 
 /// <summary>
-/// Defines how to extract and scale values from a <typeparamref name="TCoordinate"/> for encoding,
-/// reconstruct a <typeparamref name="TCoordinate"/> from scaled values for decoding,
+/// Defines how to extract and scale values from a <typeparamref name="TValue"/> for encoding,
+/// reconstruct a <typeparamref name="TValue"/> from scaled values for decoding,
 /// produce a <typeparamref name="TPolyline"/> from an encoded character buffer, and extract that buffer
 /// back from a <typeparamref name="TPolyline"/>.
 /// </summary>
-/// <typeparam name="TCoordinate">The coordinate or item type. For example a struct with Latitude/Longitude.</typeparam>
+/// <typeparam name="TValue">The coordinate or item type. For example a struct with Latitude/Longitude.</typeparam>
 /// <typeparam name="TPolyline">The polyline surface type. For example <see cref="string"/> or
 /// <see cref="ReadOnlyMemory{T}"/> of <see cref="char"/>.</typeparam>
 /// <remarks>
-/// Use <see cref="FormatterBuilder{TCoordinate, TPolyline}"/> to build a
-/// <see cref="PolylineFormatter{TCoordinate, TPolyline}"/> that implements this interface.
+/// Use <see cref="FormatterBuilder{TValue, TPolyline}"/> to build a
+/// <see cref="PolylineFormatter{TValue, TPolyline}"/> that implements this interface.
 /// </remarks>
-public interface IPolylineFormatter<TCoordinate, TPolyline> {
+public interface IPolylineFormatter<TValue, TPolyline> {
     /// <summary>
     /// Gets the number of values (columns) per encoded item.
     /// This is the required length of the <see cref="Span{T}"/> passed to <see cref="GetValues"/>
@@ -45,7 +45,7 @@ public interface IPolylineFormatter<TCoordinate, TPolyline> {
     /// <param name="values">
     /// Output buffer that receives the scaled integer values. Its length must equal <see cref="Width"/>.
     /// </param>
-    void GetValues(TCoordinate item, Span<long> values);
+    void GetValues(TValue item, Span<long> values);
 
     /// <summary>
     /// Creates a <typeparamref name="TPolyline"/> from the encoded character buffer produced by the encoder.
@@ -62,7 +62,7 @@ public interface IPolylineFormatter<TCoordinate, TPolyline> {
     ReadOnlyMemory<char> Read(TPolyline polyline);
 
     /// <summary>
-    /// Reconstructs a <typeparamref name="TCoordinate"/> from the given accumulated scaled integer values.
+    /// Reconstructs a <typeparamref name="TValue"/> from the given accumulated scaled integer values.
     /// Called once per decoded item in the decoding loop. Implementations are responsible for
     /// denormalizing the raw scaled integers (e.g. dividing by the precision factor and adding back
     /// any baseline) before constructing the item.
@@ -72,6 +72,6 @@ public interface IPolylineFormatter<TCoordinate, TPolyline> {
     /// the same column position as in <see cref="GetValues"/>. These are the direct output of the
     /// delta-accumulation loop in the decoder before any denormalization is applied.
     /// </param>
-    /// <returns>A <typeparamref name="TCoordinate"/> reconstructed from <paramref name="values"/>.</returns>
-    TCoordinate CreateItem(ReadOnlySpan<long> values);
+    /// <returns>A <typeparamref name="TValue"/> reconstructed from <paramref name="values"/>.</returns>
+    TValue CreateItem(ReadOnlySpan<long> values);
 }