feat: inline DecodeIterator into Decode, encode/decode timestamps as Unix seconds

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/07ca1843-2d5d-44b9-a4d4-ab03b37d1877

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

Author: Copilot

samples/PolylineAlgorithm.SensorData.Sample/Program.cs

@@ -34,11 +34,11 @@
 Console.WriteLine($"Encoded polyline: {encoded}");
 Console.WriteLine();
 
-// Decode (timestamps are not encoded, so they will be default)
+// Decode (timestamps and temperatures are both recovered)
 IEnumerable<SensorReading> decoded = decoder.Decode(encoded);
 
-Console.WriteLine("Decoded temperatures:");
+Console.WriteLine("Decoded readings:");
 foreach (SensorReading r in decoded)
 {
-    Console.WriteLine($"  {r.Temperature:F1} °C");
+    Console.WriteLine($"  [{r.Timestamp:HH:mm:ss}]  {r.Temperature:F1} °C");
 }

samples/PolylineAlgorithm.SensorData.Sample/SensorDataDecoder.cs

@@ -19,16 +19,12 @@ namespace PolylineAlgorithm.SensorData.Sample;
 /// scalar type, following the same structural pattern as <see cref="AbstractPolylineDecoder{TPolyline,TCoordinate}"/>.
 /// </para>
 /// <para>
-/// Because sensor data is one-dimensional (a single temperature per reading), the base class designed
-/// for two-dimensional coordinate pairs is not used. Instead, <see cref="PolylineEncoding"/> static
-/// helpers are called directly to read delta-encoded characters and denormalise the recovered values.
-/// </para>
-/// <para>
-/// Timestamps cannot be recovered from the encoded string.
-/// The decoded <see cref="SensorReading"/> instances will have <see cref="SensorReading.Timestamp"/>
-/// set to <see langword="default"/>.
+/// Each encoded pair consists of a delta-compressed Unix timestamp (seconds since Unix epoch, precision 0)
+/// followed by a delta-compressed temperature value (at <see cref="PolylineEncodingOptions.Precision"/>).
+/// Both are recovered and used to reconstruct the original <see cref="SensorReading"/>.
 /// </para>
 /// </remarks>
+[System.Diagnostics.CodeAnalysis.SuppressMessage("Sonar", "S4456:Parameter validation in yielding methods should be wrapped", Justification = "Inlined by design to demonstrate a simple iterator without a wrapper method.")]
 internal sealed class SensorDataDecoder : IPolylineDecoder<string, SensorReading> {
     /// <summary>
     /// Initializes a new instance of the <see cref="SensorDataDecoder"/> class with default encoding options.
@@ -68,8 +64,8 @@ public SensorDataDecoder(PolylineEncodingOptions options) {
     /// </param>
     /// <returns>
     /// An <see cref="IEnumerable{T}"/> of <see cref="SensorReading"/> whose
-    /// <see cref="SensorReading.Temperature"/> values are recovered from the encoded string.
-    /// <see cref="SensorReading.Timestamp"/> will be <see langword="default"/> for every element.
+    /// <see cref="SensorReading.Timestamp"/> and <see cref="SensorReading.Temperature"/> values
+    /// are recovered from the encoded string.
     /// </returns>
     /// <exception cref="ArgumentNullException">
     /// Thrown when <paramref name="polyline"/> is <see langword="null"/>.
@@ -87,23 +83,25 @@ public IEnumerable<SensorReading> Decode(string polyline, CancellationToken canc
             throw new ArgumentException("Encoded polyline must not be empty.", nameof(polyline));
         }
 
-        return DecodeIterator(polyline.AsMemory(), cancellationToken);
-    }
-
-    private IEnumerable<SensorReading> DecodeIterator(ReadOnlyMemory<char> memory, CancellationToken cancellationToken) {
+        ReadOnlyMemory<char> memory = polyline.AsMemory();
         int position = 0;
-        int accumulated = 0;
+        // Mirror the encoder's base epoch so the first delta decodes back to the correct Unix seconds.
+        int accumulatedTimestamp = SensorDataEncoder.TimestampBaseEpochSeconds;
+        int accumulatedTemperature = 0;
 
         while (position < memory.Length) {
             cancellationToken.ThrowIfCancellationRequested();
 
-            if (!PolylineEncoding.TryReadValue(ref accumulated, memory, ref position)) {
+            // Read Unix timestamp delta (precision 0) then temperature delta.
+            if (!PolylineEncoding.TryReadValue(ref accumulatedTimestamp, memory, ref position)
+                || !PolylineEncoding.TryReadValue(ref accumulatedTemperature, memory, ref position)) {
                 yield break;
             }
 
-            double temperature = PolylineEncoding.Denormalize(accumulated, Options.Precision);
+            long unixSeconds = (long)PolylineEncoding.Denormalize(accumulatedTimestamp, precision: 0);
+            double temperature = PolylineEncoding.Denormalize(accumulatedTemperature, Options.Precision);
 
-            yield return new SensorReading(default, temperature);
+            yield return new SensorReading(DateTimeOffset.FromUnixTimeSeconds(unixSeconds), temperature);
         }
     }
 }

samples/PolylineAlgorithm.SensorData.Sample/SensorDataEncoder.cs

@@ -11,24 +11,29 @@ namespace PolylineAlgorithm.SensorData.Sample;
 
 /// <summary>
 /// Encodes a sequence of <see cref="SensorReading"/> values into a compact polyline string
-/// using the polyline delta-encoding algorithm applied to the <see cref="SensorReading.Temperature"/> field.
+/// using the polyline delta-encoding algorithm applied to both the <see cref="SensorReading.Timestamp"/>
+/// and <see cref="SensorReading.Temperature"/> fields.
 /// </summary>
 /// <remarks>
 /// <para>
 /// This class demonstrates implementing <see cref="IPolylineEncoder{TValue,TPolyline}"/> for a custom
 /// scalar type, following the same structural pattern as <see cref="AbstractPolylineEncoder{TCoordinate,TPolyline}"/>.
 /// </para>
 /// <para>
-/// Because sensor readings carry only a single numeric dimension (temperature), the base class designed
-/// for two-dimensional coordinate pairs is not used. Instead, <see cref="PolylineEncoding"/> static
+/// Because sensor readings carry two numeric dimensions (timestamp and temperature), the base class designed
+/// for geographic coordinate pairs is not used. Instead, <see cref="PolylineEncoding"/> static
 /// helpers are called directly to perform normalisation, delta computation, and character-level encoding.
 /// </para>
 /// <para>
-/// Only <see cref="SensorReading.Temperature"/> values are encoded. Timestamps are not encoded and
-/// will not be recovered on decoding.
+/// Each reading is encoded as a pair of delta-compressed values:
+/// the Unix timestamp in seconds (precision 0) followed by the temperature (at <see cref="PolylineEncodingOptions.Precision"/>).
 /// </para>
 /// </remarks>
 internal sealed class SensorDataEncoder : IPolylineEncoder<SensorReading, string> {
+    // 2020-01-01 00:00:00 UTC in Unix seconds. Used as the delta-encoding base for timestamps
+    // so that the first absolute delta stays within the int32 safe range of the polyline algorithm.
+    internal const int TimestampBaseEpochSeconds = 1_577_836_800;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="SensorDataEncoder"/> class with default encoding options.
     /// </summary>
@@ -59,14 +64,15 @@ public SensorDataEncoder(PolylineEncodingOptions options) {
     /// Encodes a sequence of <see cref="SensorReading"/> values into a polyline string.
     /// </summary>
     /// <param name="coordinates">
-    /// The sensor readings whose <see cref="SensorReading.Temperature"/> values are to be encoded.
+    /// The sensor readings to encode. Each reading contributes a delta-compressed Unix timestamp
+    /// (seconds since Unix epoch, precision 0) and a delta-compressed temperature value.
     /// Must contain at least one element.
     /// </param>
     /// <param name="cancellationToken">
     /// A <see cref="CancellationToken"/> that can be used to cancel the encoding operation.
     /// </param>
     /// <returns>
-    /// A polyline-encoded string representing the delta-compressed temperature series.
+    /// A polyline-encoded string representing the delta-compressed timestamp and temperature series.
     /// </returns>
     /// <exception cref="ArgumentException">
     /// Thrown when <paramref name="coordinates"/> is empty.
@@ -83,9 +89,14 @@ public string Encode(ReadOnlySpan<SensorReading> coordinates, CancellationToken
         // using the polyline algorithm (ceil(32 bits / 5 bits per chunk) + sign bit = 7).
         const int MaxEncodedCharsPerValue = 7;
 
-        int previousNormalized = 0;
+        // Each reading encodes two values: Unix timestamp (precision 0) + temperature.
+        // The polyline algorithm uses signed int32 internally, limiting safe absolute values to ~1.07B.
+        // Current Unix time in seconds (~1.74B) exceeds this. We therefore delta-encode relative to
+        // 2020-01-01 00:00:00 UTC (= 1 577 836 800 s), keeping the initial delta well within range.
+        int previousTimestampNormalized = TimestampBaseEpochSeconds;
+        int previousTemperatureNormalized = 0;
         int position = 0;
-        int length = coordinates.Length * MaxEncodedCharsPerValue;
+        int length = coordinates.Length * 2 * MaxEncodedCharsPerValue;
 
         char[]? temp = length <= Options.StackAllocLimit
             ? null
@@ -97,14 +108,21 @@ public string Encode(ReadOnlySpan<SensorReading> coordinates, CancellationToken
             for (int i = 0; i < coordinates.Length; i++) {
                 cancellationToken.ThrowIfCancellationRequested();
 
-                int normalized = PolylineEncoding.Normalize(coordinates[i].Temperature, Options.Precision);
-                int delta = normalized - previousNormalized;
+                // Encode Unix timestamp in whole seconds (precision 0).
+                int normalizedTimestamp = PolylineEncoding.Normalize((double)coordinates[i].Timestamp.ToUnixTimeSeconds(), precision: 0);
+                int timestampDelta = normalizedTimestamp - previousTimestampNormalized;
+
+                // Encode temperature at the configured precision.
+                int normalizedTemperature = PolylineEncoding.Normalize(coordinates[i].Temperature, Options.Precision);
+                int temperatureDelta = normalizedTemperature - previousTemperatureNormalized;
 
-                if (!PolylineEncoding.TryWriteValue(delta, buffer, ref position)) {
+                if (!PolylineEncoding.TryWriteValue(timestampDelta, buffer, ref position)
+                    || !PolylineEncoding.TryWriteValue(temperatureDelta, buffer, ref position)) {
                     throw new InvalidOperationException("Encoding buffer is too small to hold the encoded value.");
                 }
 
-                previousNormalized = normalized;
+                previousTimestampNormalized = normalizedTimestamp;
+                previousTemperatureNormalized = normalizedTemperature;
             }
 
             return buffer[..position].ToString();