feat: add SensorData sample project files (encoder, decoder, model)

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/32504d4d-88c9-40a1-aace-d0c432a0ef9b

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

Author: Copilot

samples/PolylineAlgorithm.SensorData.Sample/PolylineAlgorithm.SensorData.Sample.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+	<PropertyGroup>
+		<TargetFramework>netstandard2.1</TargetFramework>
+	</PropertyGroup>
+
+	<PropertyGroup>
+		<IsPackable>false</IsPackable>
+	</PropertyGroup>
+
+	<ItemGroup>
+	  <ProjectReference Include="..\..\src\PolylineAlgorithm\PolylineAlgorithm.csproj" />
+	</ItemGroup>
+
+</Project>

samples/PolylineAlgorithm.SensorData.Sample/Properties/CodeCoverage.cs

@@ -0,0 +1,8 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+using System.Diagnostics.CodeAnalysis;
+
+[assembly: ExcludeFromCodeCoverage]

samples/PolylineAlgorithm.SensorData.Sample/SensorDataDecoder.cs

@@ -0,0 +1,110 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.SensorData.Sample;
+
+using PolylineAlgorithm.Abstraction;
+using System.Collections.Generic;
+using System.Threading;
+
+/// <summary>
+/// Decodes a compact polyline string produced by <see cref="SensorDataEncoder"/> back into a sequence
+/// of <see cref="SensorReading"/> values.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This class demonstrates implementing <see cref="IPolylineDecoder{TPolyline,TValue}"/> for a custom
+/// 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"/>.
+/// </para>
+/// </remarks>
+public sealed class SensorDataDecoder : IPolylineDecoder<string, SensorReading> {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SensorDataDecoder"/> class with default encoding options.
+    /// </summary>
+    public SensorDataDecoder()
+        : this(new PolylineEncodingOptions()) { }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SensorDataDecoder"/> class with the specified encoding options.
+    /// </summary>
+    /// <param name="options">
+    /// The <see cref="PolylineEncodingOptions"/> to use for decoding operations.
+    /// The <see cref="PolylineEncodingOptions.Precision"/> value must match the precision used during encoding.
+    /// </param>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="options"/> is <see langword="null"/>.
+    /// </exception>
+    public SensorDataDecoder(PolylineEncodingOptions options) {
+        if (options is null) {
+            throw new ArgumentNullException(nameof(options));
+        }
+
+        Options = options;
+    }
+
+    /// <summary>
+    /// Gets the encoding options used by this decoder.
+    /// </summary>
+    public PolylineEncodingOptions Options { get; }
+
+    /// <summary>
+    /// Decodes a polyline string back into a sequence of <see cref="SensorReading"/> values.
+    /// </summary>
+    /// <param name="polyline">
+    /// The polyline-encoded string produced by <see cref="SensorDataEncoder.Encode"/>.
+    /// </param>
+    /// <param name="cancellationToken">
+    /// A <see cref="CancellationToken"/> that can be used to cancel the decoding operation.
+    /// </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.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="polyline"/> is <see langword="null"/>.
+    /// </exception>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="polyline"/> is empty.
+    /// </exception>
+    /// <exception cref="OperationCanceledException">
+    /// Thrown when <paramref name="cancellationToken"/> requests cancellation.
+    /// </exception>
+    public IEnumerable<SensorReading> Decode(string polyline, CancellationToken cancellationToken = default) {
+        if (polyline is null) {
+            throw new ArgumentNullException(nameof(polyline));
+        }
+
+        if (polyline.Length < 1) {
+            throw new ArgumentException("Encoded polyline must not be empty.", nameof(polyline));
+        }
+
+        ReadOnlyMemory<char> memory = polyline.AsMemory();
+        int position = 0;
+        int accumulated = 0;
+
+        while (position < memory.Length) {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            if (!PolylineEncoding.TryReadValue(ref accumulated, memory, ref position)) {
+                yield break;
+            }
+
+            double temperature = PolylineEncoding.Denormalize(accumulated, Options.Precision);
+
+            yield return new SensorReading(default, temperature);
+        }
+    }
+}

samples/PolylineAlgorithm.SensorData.Sample/SensorDataEncoder.cs

@@ -0,0 +1,119 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.SensorData.Sample;
+
+using PolylineAlgorithm.Abstraction;
+using System.Buffers;
+using System.Threading;
+
+/// <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.
+/// </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
+/// 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.
+/// </para>
+/// </remarks>
+public sealed class SensorDataEncoder : IPolylineEncoder<SensorReading, string> {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SensorDataEncoder"/> class with default encoding options.
+    /// </summary>
+    public SensorDataEncoder()
+        : this(new PolylineEncodingOptions()) { }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SensorDataEncoder"/> class with the specified encoding options.
+    /// </summary>
+    /// <param name="options">
+    /// The <see cref="PolylineEncodingOptions"/> to use for encoding operations.
+    /// </param>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="options"/> is <see langword="null"/>.
+    /// </exception>
+    public SensorDataEncoder(PolylineEncodingOptions options) {
+        if (options is null) {
+            throw new ArgumentNullException(nameof(options));
+        }
+
+        Options = options;
+    }
+
+    /// <summary>
+    /// Gets the encoding options used by this encoder.
+    /// </summary>
+    public PolylineEncodingOptions Options { get; }
+
+    /// <summary>
+    /// 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.
+    /// 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.
+    /// </returns>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="coordinates"/> is empty.
+    /// </exception>
+    /// <exception cref="OperationCanceledException">
+    /// Thrown when <paramref name="cancellationToken"/> requests cancellation.
+    /// </exception>
+    public string Encode(ReadOnlySpan<SensorReading> coordinates, CancellationToken cancellationToken = default) {
+        if (coordinates.Length < 1) {
+            throw new ArgumentException("Sequence must contain at least one element.", nameof(coordinates));
+        }
+
+        // Maximum number of ASCII characters required to encode a single 32-bit delta value
+        // using the polyline algorithm (ceil(32 bits / 5 bits per chunk) + sign bit = 7).
+        const int MaxEncodedCharsPerValue = 7;
+
+        int previousNormalized = 0;
+        int position = 0;
+        int length = coordinates.Length * MaxEncodedCharsPerValue;
+
+        char[]? temp = length <= Options.StackAllocLimit
+            ? null
+            : ArrayPool<char>.Shared.Rent(length);
+
+        Span<char> buffer = temp is null ? stackalloc char[length] : temp.AsSpan(0, length);
+
+        try {
+            for (int i = 0; i < coordinates.Length; i++) {
+                cancellationToken.ThrowIfCancellationRequested();
+
+                int normalized = PolylineEncoding.Normalize(coordinates[i].Temperature, Options.Precision);
+                int delta = normalized - previousNormalized;
+
+                if (!PolylineEncoding.TryWriteValue(delta, buffer, ref position)) {
+                    throw new InvalidOperationException("Encoding buffer is too small to hold the encoded value.");
+                }
+
+                previousNormalized = normalized;
+            }
+
+            return buffer[..position].ToString();
+        } finally {
+            if (temp is not null) {
+                ArrayPool<char>.Shared.Return(temp);
+            }
+        }
+    }
+}

samples/PolylineAlgorithm.SensorData.Sample/SensorReading.cs

@@ -0,0 +1,13 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.SensorData.Sample;
+
+/// <summary>
+/// Represents a single temperature reading captured by a sensor.
+/// </summary>
+/// <param name="Timestamp">The UTC time at which the reading was captured.</param>
+/// <param name="Temperature">The temperature value of the reading, in degrees Celsius.</param>
+public readonly record struct SensorReading(DateTimeOffset Timestamp, double Temperature);