Changes before error encountered

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/1ae1dd3f-582a-4277-8da4-f0572c87aed3

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

Author: Copilot

benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncodingBenchmark.cs

@@ -1,10 +1,20 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
 namespace PolylineAlgorithm.Benchmarks;
 
 using BenchmarkDotNet.Attributes;
 using PolylineAlgorithm.Utility;
 
+/// <summary>
+/// Benchmarks for the polyline encoding validation methods in <see cref="PolylineEncoding"/>.
+/// </summary>
 public class PolylineEncodingBenchmark {
+#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.
     private string polyline;
+#pragma warning restore CS8618
 
     /// <summary>
     /// Number of coordinates for benchmarks. Set by BenchmarkDotNet.

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs

@@ -35,7 +35,8 @@ protected override double GetLatitude(Point current) {
             throw new ArgumentNullException(nameof(current));
         }
 
-        return current.X;
+        // NetTopologySuite Point: Y = latitude
+        return current.Y;
     }
 
     /// <summary>
@@ -48,6 +49,7 @@ protected override double GetLongitude(Point current) {
             throw new ArgumentNullException(nameof(current));
         }
 
-        return current.Y;
+        // NetTopologySuite Point: X = longitude
+        return current.X;
     }
 }

src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs

@@ -26,6 +26,7 @@ namespace PolylineAlgorithm.Abstraction;
 /// <typeparam name="TPolyline">The type that represents the encoded polyline output.</typeparam>
 public abstract class AbstractPolylineEncoder<TCoordinate, TPolyline> : IPolylineEncoder<TCoordinate, TPolyline> {
     private readonly ILogger<AbstractPolylineEncoder<TCoordinate, TPolyline>> _logger;
+
     /// <summary>
     /// Initializes a new instance of the <see cref="AbstractPolylineEncoder{TCoordinate, TPolyline}"/> class with default encoding options.
     /// </summary>
@@ -99,6 +100,8 @@ public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates, CancellationToken
 
         Span<char> buffer = temp is null ? stackalloc char[length] : temp.AsSpan(0, length);
 
+        string encodedResult;
+
         try {
             for (var i = 0; i < coordinates.Length; i++) {
                 cancellationToken.ThrowIfCancellationRequested();
@@ -124,6 +127,8 @@ public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates, CancellationToken
 
                 consumed++;
             }
+
+            encodedResult = buffer[..position].ToString();
         } finally {
             if (temp is not null) {
                 ArrayPool<char>.Shared.Return(temp);
@@ -133,7 +138,7 @@ public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates, CancellationToken
         _logger
             .LogOperationFinishedDebug(OperationName);
 
-        return CreatePolyline(buffer[..position].ToString().AsMemory());
+        return CreatePolyline(encodedResult.AsMemory());
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         static int GetMaxBufferLength(int count) {

src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs

@@ -0,0 +1,97 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Extensions;
+
+using PolylineAlgorithm.Abstraction;
+using PolylineAlgorithm.Internal.Diagnostics;
+using System;
+using System.Collections.Generic;
+
+/// <summary>
+/// Provides extension methods for the <see cref="IPolylineDecoder{TPolyline, TValue}"/> interface to facilitate decoding encoded polylines.
+/// </summary>
+public static class PolylineDecoderExtensions {
+    /// <summary>
+    /// Decodes an encoded polyline represented as a character array into a sequence of geographic coordinates.
+    /// </summary>
+    /// <typeparam name="TValue">The coordinate type returned by the decoder.</typeparam>
+    /// <param name="decoder">
+    /// The <see cref="IPolylineDecoder{TPolyline, TValue}"/> instance used to perform the decoding operation.
+    /// </param>
+    /// <param name="polyline">
+    /// The encoded polyline as a character array to decode. The array is converted to a string internally.
+    /// </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>
+    public static IEnumerable<TValue> Decode<TValue>(this IPolylineDecoder<string, TValue> decoder, char[] polyline) {
+        if (decoder is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(decoder));
+        }
+
+        if (polyline is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(polyline));
+        }
+
+        return decoder.Decode(new string(polyline));
+    }
+
+    /// <summary>
+    /// Decodes an encoded polyline represented as a read-only memory of characters into a sequence of geographic coordinates.
+    /// </summary>
+    /// <typeparam name="TValue">The coordinate type returned by the decoder.</typeparam>
+    /// <param name="decoder">
+    /// The <see cref="IPolylineDecoder{TPolyline, TValue}"/> instance used to perform the decoding operation.
+    /// </param>
+    /// <param name="polyline">
+    /// The encoded polyline as a read-only memory of characters to decode. The memory is converted to a string internally.
+    /// </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"/> is <see langword="null"/>.
+    /// </exception>
+    public static IEnumerable<TValue> Decode<TValue>(this IPolylineDecoder<string, TValue> decoder, ReadOnlyMemory<char> polyline) {
+        if (decoder is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(decoder));
+        }
+
+        return decoder.Decode(polyline.ToString());
+    }
+
+    /// <summary>
+    /// Decodes an encoded polyline string into a sequence of geographic coordinates,
+    /// using a decoder that accepts <see cref="ReadOnlyMemory{T}"/> of <see cref="char"/>.
+    /// </summary>
+    /// <typeparam name="TValue">The coordinate type returned by the decoder.</typeparam>
+    /// <param name="decoder">
+    /// The <see cref="IPolylineDecoder{TPolyline, TValue}"/> instance used to perform the decoding operation.
+    /// </param>
+    /// <param name="polyline">
+    /// The encoded polyline string to decode. The string is converted to <see cref="ReadOnlyMemory{T}"/> internally.
+    /// </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>
+    public static IEnumerable<TValue> Decode<TValue>(this IPolylineDecoder<ReadOnlyMemory<char>, TValue> decoder, string polyline) {
+        if (decoder is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(decoder));
+        }
+
+        if (polyline is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(polyline));
+        }
+
+        return decoder.Decode(polyline.AsMemory());
+    }
+}

src/PolylineAlgorithm/Extensions/PolylineDecoderExtensions.cs

@@ -206,6 +206,12 @@ public static void ThrowInvalidPolylineFormat(long position) {
     /// <summary>
     /// Throws an <see cref="InvalidPolylineException"/> when the polyline block terminator is invalid.
     /// </summary>
+#if NET6_0_OR_GREATER
+    [StackTraceHidden]
+#else
+    [MethodImpl(MethodImplOptions.NoInlining)]
+#endif
+    [DoesNotReturn]
     public static void ThrowInvalidPolylineBlockTerminator() {
         throw new InvalidPolylineException(ExceptionMessage.GetInvalidPolylineBlockTerminator());
     }
@@ -240,6 +246,7 @@ internal static class ExceptionMessage {
 #endif
 
         private static readonly string ArgumentCannotBeEmptyMessage = ExceptionMessageResource.ArgumentCannotBeEmptyMessage;
+        private static readonly string ArgumentValueMustBeFiniteNumberMessage = ExceptionMessageResource.ArgumentValueMustBeFiniteNumber;
         private static readonly string CouldNotWriteEncodedValueToTheBufferMessage = ExceptionMessageResource.CouldNotWriteEncodedValueToTheBufferMessage;
         private static readonly string InvalidPolylineBlockTerminatorMessage = ExceptionMessageResource.InvalidPolylineBlockTerminatorMessage;
 
@@ -295,7 +302,7 @@ public static string FormatInvalidPolylineLength(int length, int min) =>
         /// Gets the message used when a numeric argument must be finite.
         /// </summary>
         public static string GetArgumentValueMustBeFiniteNumber() =>
-            ArgumentCannotBeEmptyMessage;
+            ArgumentValueMustBeFiniteNumberMessage;
 
         /// <summary>
         /// Gets the message used when the library could not write an encoded value to a buffer.

src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs

@@ -7,19 +7,51 @@ namespace PolylineAlgorithm.Internal.Diagnostics;
 
 using Microsoft.Extensions.Logging;
 
+/// <summary>
+/// Provides strongly-typed logging extension methods for debug-level diagnostics used throughout the library.
+/// These methods are partial and annotated with <see cref="LoggerMessageAttribute"/> so the .NET
+/// source generator can produce efficient logging implementations at compile time.
+/// </summary>
+/// <remarks>
+/// Event IDs are derived from the debug <see cref="LogLevel"/> value: <c>(int)LogLevel.Debug * 100</c>.
+/// For the current <see cref="LogLevel.Debug"/> value this yields a base of <c>100</c>,
+/// so individual event IDs range from <c>101</c> to <c>104</c>.
+/// </remarks>
 internal static partial class LogDebugExtensions {
     private const LogLevel LOG_LEVEL = LogLevel.Debug;
     private const int EVENT_ID_BASE = (int)LOG_LEVEL * Defaults.Logging.LogLevelMultiplier;
 
+    /// <summary>
+    /// Logs a debug message when an operation has started.
+    /// </summary>
+    /// <param name="logger">The <see cref="ILogger"/> used to write the log entry.</param>
+    /// <param name="operationName">The name of the operation that has started.</param>
     [LoggerMessage(EVENT_ID_BASE + 1, LOG_LEVEL, "Operation {operationName} has started.")]
     internal static partial void LogOperationStartedDebug(this ILogger logger, string operationName);
 
+    /// <summary>
+    /// Logs a debug message when an operation has failed.
+    /// </summary>
+    /// <param name="logger">The <see cref="ILogger"/> used to write the log entry.</param>
+    /// <param name="operationName">The name of the operation that has failed.</param>
     [LoggerMessage(EVENT_ID_BASE + 2, LOG_LEVEL, "Operation {operationName} has failed.")]
     internal static partial void LogOperationFailedDebug(this ILogger logger, string operationName);
 
+    /// <summary>
+    /// Logs a debug message when an operation has finished successfully.
+    /// </summary>
+    /// <param name="logger">The <see cref="ILogger"/> used to write the log entry.</param>
+    /// <param name="operationName">The name of the operation that has finished.</param>
     [LoggerMessage(EVENT_ID_BASE + 3, LOG_LEVEL, "Operation {operationName} has finished.")]
     internal static partial void LogOperationFinishedDebug(this ILogger logger, string operationName);
 
+    /// <summary>
+    /// Logs a debug message containing the decoded coordinate values and position.
+    /// </summary>
+    /// <param name="logger">The <see cref="ILogger"/> used to write the log entry.</param>
+    /// <param name="latitude">The decoded latitude value.</param>
+    /// <param name="longitude">The decoded longitude value.</param>
+    /// <param name="position">The position in the polyline buffer at which the coordinate was decoded.</param>
     [LoggerMessage(EVENT_ID_BASE + 4, LOG_LEVEL, "Decoded coordinate: (Latitude: {latitude}, Longitude: {longitude}) at position {position}.")]
     internal static partial void LogDecodedCoordinateDebug(this ILogger logger, double latitude, double longitude, int position);
-}
+}

src/PolylineAlgorithm/Internal/Diagnostics/LogDebugExtensions.cs

@@ -4,14 +4,6 @@
 		<TargetFramework>netstandard2.1</TargetFramework>
 	</PropertyGroup>
 
-	<!--<PropertyGroup>
-		<RunCodeAnalysis>true</RunCodeAnalysis>
-		<AnalysisMode>Recommended</AnalysisMode>
-		<EnableNETAnalyzers>true</EnableNETAnalyzers>
-		<WarningLevel>4</WarningLevel>
-		<AnalysisLevel>latest</AnalysisLevel>
-	</PropertyGroup>-->
-
 	<PropertyGroup>
 		<GenerateDocumentationFile>True</GenerateDocumentationFile>
 	</PropertyGroup>
@@ -52,7 +44,6 @@
 			<IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
 		</PackageReference>
 		<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="[6.0.0,11.0.0)" />
-		<PackageReference Include="System.Text.Json" Version="10.0.5" />
 	</ItemGroup>
 
 	<ItemGroup>

src/PolylineAlgorithm/PolylineAlgorithm.csproj

@@ -118,7 +118,7 @@
     <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
   </resheader>
   <data name="ArgumentCannotBeEmptyMessage" xml:space="preserve">
-    <value>Argument cannot be an empty.</value>
+    <value>Argument cannot be empty.</value>
   </data>
   <data name="PolylineIsMalformedAtFormat" xml:space="preserve">
     <value>Polyline is malformed at position {0}.</value>
@@ -129,9 +129,6 @@
   <data name="ArgumentValueMustBeFiniteNumber" xml:space="preserve">
     <value>Value must be a finite number.</value>
   </data>
-  <data name="ArgumentOutOfRangeFormat" xml:space="preserve">
-    <value> Value {0} is out of range. Expected range between {1} and {2}.</value>
-  </data>
   <data name="StackAllocLimitMustBeEqualOrGreaterThanFormat" xml:space="preserve">
     <value>Stack alloc limit must be equal or greater than {0}.</value>
   </data>