refactored exceptions and stuff around diagnostics.

Author: petesramek

src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs

@@ -7,22 +7,21 @@
 using PolylineAlgorithm;
 using PolylineAlgorithm.Diagnostics;
 using PolylineAlgorithm.Internal;
+using PolylineAlgorithm.Internal.Diagnostics;
 using PolylineAlgorithm.Internal.Logging;
 using System;
 using System.Runtime.CompilerServices;
 using System.Threading;
 
-namespace PolylineAlgorithm.Abstraction
-{
+namespace PolylineAlgorithm.Abstraction {
     /// <summary>
     /// Decodes encoded polyline strings into sequences of geographic coordinates.
     /// Implements the <see cref="IPolylineDecoder{TPolyline, TCoordinate}"/> interface.
     /// </summary>
     /// <remarks>
     /// This abstract class provides a base implementation for decoding polylines, allowing subclasses to define how to handle specific polyline formats.
     /// </remarks>
-    public abstract class AbstractPolylineDecoder<TPolyline, TCoordinate> : IPolylineDecoder<TPolyline, TCoordinate>
-    {
+    public abstract class AbstractPolylineDecoder<TPolyline, TCoordinate> : IPolylineDecoder<TPolyline, TCoordinate> {
         private readonly ILogger<AbstractPolylineDecoder<TPolyline, TCoordinate>> _logger;
 
         /// <summary>
@@ -40,10 +39,15 @@ protected AbstractPolylineDecoder()
         /// <exception cref="ArgumentNullException">
         /// Thrown when <paramref name="encodingOptions"/> is <see langword="null" />
         /// </exception>
-        protected AbstractPolylineDecoder(PolylineEncodingOptions encodingOptions)
-        {
-            Options = encodingOptions ?? throw new ArgumentNullException(nameof(encodingOptions));
-            _logger = Options.LoggerFactory.CreateLogger<AbstractPolylineDecoder<TPolyline, TCoordinate>>();
+        protected AbstractPolylineDecoder(PolylineEncodingOptions options) {
+            if(options is null) {
+                ExceptionGuard.ThrowArgumentNull(nameof(options));
+            }
+
+            Options = options;
+            _logger = Options
+                .LoggerFactory
+                .CreateLogger<AbstractPolylineDecoder<TPolyline, TCoordinate>>();
         }
 
         /// <summary>
@@ -81,99 +85,83 @@ public IEnumerable<TCoordinate> Decode(TPolyline polyline)
         /// <exception cref="ArgumentNullException"/>
         /// <exception cref="ArgumentException"/>
         /// <exception cref="InvalidPolylineException"/>
-        public IEnumerable<TCoordinate> Decode(TPolyline polyline, CancellationToken cancellationToken)
-        {
+        public IEnumerable<TCoordinate> Decode(TPolyline polyline, CancellationToken cancellationToken) {
             const string OperationName = nameof(Decode);
 
             _logger?.LogOperationStartedDebug(OperationName);
 
             ValidateNullPolyline(polyline, _logger);
 
-            ReadOnlyMemory<char> polylineSequence = GetReadOnlyMemory(in polyline);
+            ReadOnlyMemory<char> sequence = GetReadOnlyMemory(in polyline);
 
-            ValidateEmptySequence(polylineSequence, _logger);
-            ValidateFormat(polylineSequence, _logger);
+            ValidateSequence(sequence, _logger);
+            ValidateFormat(sequence, _logger);
 
-            int currentPosition = 0;
+            int position = 0;
             int encodedLatitude = 0;
             int encodedLongitude = 0;
 
-            try
-            {
-                while (currentPosition < polylineSequence.Length)
-                {
+            try {
+                while (position < sequence.Length) {
                     cancellationToken.ThrowIfCancellationRequested();
 
-                    if (!PolylineEncoding.TryReadValue(ref encodedLatitude, polylineSequence, ref currentPosition)
-                        || !PolylineEncoding.TryReadValue(ref encodedLongitude, polylineSequence, ref currentPosition))
-                    {
+                    if (!PolylineEncoding.TryReadValue(ref encodedLatitude, sequence, ref position)
+                        || !PolylineEncoding.TryReadValue(ref encodedLongitude, sequence, ref position)) {
                         _logger?.LogOperationFailedDebug(OperationName);
-                        _logger?.LogInvalidPolylineWarning(currentPosition);
+                        _logger?.LogInvalidPolylineWarning(position);
 
-                        OnInvalidPolyline(currentPosition, polylineSequence);
-                        InvalidPolylineException.Throw(currentPosition);
+                        OnInvalidPolyline(position, sequence);
+                        ExceptionGuard.ThrowInvalidPolylineFormat(position);
                     }
 
                     double decodedLatitude = PolylineEncoding.Denormalize(encodedLatitude, Options.Precision);
                     double decodedLongitude = PolylineEncoding.Denormalize(encodedLongitude, Options.Precision);
 
-                    _logger?.LogDecodedCoordinateDebug(decodedLatitude, decodedLongitude, currentPosition);
+                    _logger?.LogDecodedCoordinateDebug(decodedLatitude, decodedLongitude, position);
 
                     yield return CreateCoordinate(decodedLatitude, decodedLongitude);
                 }
-            }
-            finally
-            {
+            } finally {
                 _logger?.LogOperationFinishedDebug(OperationName);
             }
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static void ValidateNullPolyline(TPolyline polyline, ILogger logger)
-        {
-            if (polyline is null)
-            {
+        private static void ValidateNullPolyline(TPolyline polyline, ILogger? logger) {
+            if (polyline is null) {
                 logger?.LogNullArgumentWarning(nameof(polyline));
-                throw new ArgumentNullException(nameof(polyline), "Polyline argument cannot be null.");
+                ExceptionGuard.ThrowArgumentNull(nameof(polyline));
             }
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private static void ValidateEmptySequence(ReadOnlyMemory<char> polylineSequence, ILogger logger)
-        {
-            if (polylineSequence.Length < Defaults.Polyline.Block.Length.Min)
-            {
+        private static void ValidateSequence(ReadOnlyMemory<char> polylineSequence, ILogger? logger) {
+            if (polylineSequence.Length < Defaults.Polyline.Block.Length.Min) {
                 logger?.LogOperationFailedDebug(nameof(Decode));
-                logger?.LogPolylineCannotBeShorterThanWarning(nameof(polylineSequence), polylineSequence.Length, Defaults.Polyline.Block.Length.Min);
+                logger?.LogPolylineCannotBeShorterThanWarning(polylineSequence.Length, Defaults.Polyline.Block.Length.Min);
 
-                throw new ArgumentException(
-                    $"Polyline must be at least {Defaults.Polyline.Block.Length.Min} characters long, but was {polylineSequence.Length}.",
-                    nameof(polylineSequence));
+                ExceptionGuard.ThrowInvalidPolylineLength(polylineSequence.Length, Defaults.Polyline.Block.Length.Min);
             }
         }
 
         /// <summary>
         /// Validates the polyline format for allowed characters.
         /// </summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        protected virtual void ValidateFormat(ReadOnlyMemory<char> polylineSequence, ILogger logger)
-        {
-            try
-            {
-                PolylineEncoding.Validation.ValidateFormat(polylineSequence.Span);
-            }
-            catch (ArgumentException ex)
-            {
-                logger?.LogWarning(ex.Message);
+        protected virtual void ValidateFormat(ReadOnlyMemory<char> sequence, ILogger? logger) {
+            try {
+                PolylineEncoding.Validation.ValidateFormat(sequence.Span);
+            } catch (ArgumentException ex) {
+                logger?.LogInvalidPolylineFormatWarning(ex);
+
                 throw;
             }
         }
 
         /// <summary>
         /// Hook for subclasses to handle invalid polyline cases.
         /// </summary>
-        protected virtual void OnInvalidPolyline(int position, ReadOnlyMemory<char> polylineSequence)
-        {
+        protected virtual void OnInvalidPolyline(int position, ReadOnlyMemory<char> polylineSequence) {
             // Subclasses can override for custom error handling/logging.
         }
 

src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs

@@ -39,7 +39,11 @@ protected AbstractPolylineEncoder()
     /// </param>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="options"/> is <see langword="null" /></exception>
     protected AbstractPolylineEncoder(PolylineEncodingOptions options) {
-        Options = options ?? throw new ArgumentNullException(nameof(options));
+        if (options is null) {
+            ExceptionGuard.ThrowArgumentNull(nameof(options));
+        }
+
+        Options = options;
         _logger = Options
             .LoggerFactory
             .CreateLogger<AbstractPolylineEncoder<TCoordinate, TPolyline>>();
@@ -108,7 +112,8 @@ public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates) {
                     _logger
                         .LogCannotWriteValueToBufferWarning(position, consumed);
 
-                    throw new InvalidOperationException(ExceptionMessages.GetCouldNotWriteEncodedValueToTheBuffer());
+                    ExceptionGuard.ThrowCouldNotWriteEncodedValueToBuffer();
+                    
                 }
 
                 consumed++;
@@ -143,7 +148,7 @@ static void ValidateEmptyCoordinates(ref ReadOnlySpan<TCoordinate> coordinates,
                 logger
                     .LogEmptyArgumentWarning(nameof(coordinates));
 
-                throw new ArgumentException(ExceptionMessages.GetArgumentCannotBeEmptyEnumerationMessage(), nameof(coordinates));
+                ExceptionGuard.ThrwoArgumentCannotBeEmptyEnumerationMessage(nameof(coordinates));
             }
         }
     }

src/PolylineAlgorithm/Coordinate.cs

@@ -9,6 +9,7 @@ namespace PolylineAlgorithm;
 using System;
 using System.Diagnostics;
 using System.Globalization;
+using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
 /// <summary>
@@ -23,16 +24,14 @@ namespace PolylineAlgorithm;
 /// </remarks>
 [DebuggerDisplay("{ToString()}")]
 [StructLayout(LayoutKind.Auto)]
-public readonly struct Coordinate : IEquatable<Coordinate>      
-{
+public readonly struct Coordinate : IEquatable<Coordinate> {
     /// <summary>
     /// Initializes a new instance of the <see cref="Coordinate"/> struct with default values (0) for <see cref="Latitude"/> and <see cref="Longitude"/>.
     /// </summary>
     /// <remarks>
     /// The default value (0, 0) is a valid coordinate (Gulf of Guinea), but is also treated as the "default" value by <see cref="IsDefault"/>.
     /// </remarks>
-    public Coordinate()
-    {
+    public Coordinate() {
         Latitude = default;
         Longitude = default;
     }
@@ -50,10 +49,8 @@ public Coordinate()
     /// Thrown when <paramref name="latitude"/> is less than -90 or greater than 90,
     /// or when <paramref name="longitude"/> is less than -180 or greater than 180.
     /// </exception>
-    public Coordinate(double latitude, double longitude)
-    {
-        Validation.ValidateLatitude(latitude);
-        Validation.ValidateLongitude(longitude);
+    public Coordinate(double latitude, double longitude) {
+        Validator.Validate(latitude, longitude);
 
         Latitude = latitude;
         Longitude = longitude;
@@ -86,8 +83,7 @@ public bool IsDefault()
     public override bool Equals(object? obj) => obj is Coordinate coordinate && Equals(coordinate);
 
     /// <inheritdoc />
-    public bool Equals(Coordinate other)
-    {
+    public bool Equals(Coordinate other) {
         return Latitude.Equals(other.Latitude) &&
                Longitude.Equals(other.Longitude);
     }
@@ -113,8 +109,7 @@ public bool Equals(Coordinate other, double tolerance)
     /// <returns>
     /// A string representation of the coordinate.
     /// </returns>
-    public override string ToString()
-    {
+    public override string ToString() {
         return $"{{ {nameof(Latitude)}: {Latitude.ToString("G", CultureInfo.InvariantCulture)}, {nameof(Longitude)}: {Longitude.ToString("G", CultureInfo.InvariantCulture)} }}";
     }
 
@@ -139,38 +134,80 @@ public override string ToString()
     public static bool operator !=(Coordinate left, Coordinate right) => !(left == right);
 
     /// <summary>
-    /// Provides validation methods for latitude and longitude values used in <see cref="Coordinate"/>.
+    /// Provides static methods for validating latitude and longitude values used in <see cref="Coordinate"/>.
     /// </summary>
-    internal static class Validation
-    {
+    /// <remarks>
+    /// The <c>Validator</c> class ensures that latitude and longitude values are within their valid ranges:
+    /// <list type="bullet">
+    /// <item>
+    /// <description>Latitude must be between -90 and 90 degrees.</description>
+    /// </item>
+    /// <item>
+    /// <description>Longitude must be between -180 and 180 degrees.</description>
+    /// </item>
+    /// </list>
+    /// If a value is out of range or not finite, an exception is thrown via <see cref="ExceptionGuard.ThrowCoordinateValueOutOfRange"/>.
+    /// </remarks>
+    public static class Validator {
         /// <summary>
-        /// Validates that the specified latitude is within the valid range of -90 to 90 degrees and is a finite value.
+        /// Validates that the specified latitude is within the valid range of -90 to 90 degrees.
         /// </summary>
         /// <param name="latitude">The latitude value to validate.</param>
         /// <exception cref="ArgumentOutOfRangeException">
-        /// Thrown when <paramref name="latitude"/> is less than -90, greater than 90, or not a finite value.
+        /// Thrown if <paramref name="latitude"/> is less than -90, greater than 90, or not a finite number.
         /// </exception>
-        internal static void ValidateLatitude(double latitude)
-        {
-            if (latitude < -90 || latitude > 90 || !double.IsFinite(latitude))
-            {
-                throw new ArgumentOutOfRangeException(nameof(latitude), ExceptionMessages.FormatCoordinateValueMustBeBetween("latitude", -90, 90));
-            }
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void ValidateLatitude(double latitude) {
+            const double min = -90;
+            const double max = 90;
+
+            ValidateValue(latitude, min, max, nameof(latitude));
         }
 
         /// <summary>
-        /// Validates that the specified longitude is within the valid range of -180 to 180 degrees and is a finite value.
+        /// Validates that the specified longitude is within the valid range of -180 to 180 degrees.
         /// </summary>
         /// <param name="longitude">The longitude value to validate.</param>
         /// <exception cref="ArgumentOutOfRangeException">
-        /// Thrown when <paramref name="longitude"/> is less than -180, greater than 180, or not a finite value.
+        /// Thrown if <paramref name="longitude"/> is less than -180, greater than 180, or not a finite number.
         /// </exception>
-        internal static void ValidateLongitude(double longitude)
-        {
-            if (longitude < -180 || longitude > 180 || !double.IsFinite(longitude))
-            {
-                throw new ArgumentOutOfRangeException(nameof(longitude), ExceptionMessages.FormatCoordinateValueMustBeBetween("Longitude", -180, 180));
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void ValidateLongitude(double longitude) {
+            const double min = -180;
+            const double max = 180;
+
+            ValidateValue(longitude, min, max, nameof(longitude));
+        }
+
+        /// <summary>
+        /// Validates that the specified value is finite and within the specified range.
+        /// </summary>
+        /// <param name="value">The value to validate.</param>
+        /// <param name="min">The minimum allowed value (inclusive).</param>
+        /// <param name="max">The maximum allowed value (inclusive).</param>
+        /// <param name="paramName">The name of the parameter being validated.</param>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// Thrown if <paramref name="value"/> is not finite, less than <paramref name="min"/>, or greater than <paramref name="max"/>.
+        /// </exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void ValidateValue(double value, double min, double max, string paramName) {
+            if (!double.IsFinite(value) || value < min || value > max) {
+                ExceptionGuard.ThrowCoordinateValueOutOfRange(value, min, max, paramName);
             }
         }
+
+        /// <summary>
+        /// Validates both latitude and longitude values for a coordinate.
+        /// </summary>
+        /// <param name="latitude">The latitude value to validate.</param>
+        /// <param name="longitude">The longitude value to validate.</param>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// Thrown if either <paramref name="latitude"/> or <paramref name="longitude"/> is out of range or not finite.
+        /// </exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static void Validate(double latitude, double longitude) {
+            ValidateLatitude(latitude);
+            ValidateLongitude(longitude);
+        }
     }
 }

src/PolylineAlgorithm/Diagnostics/InvalidPolylineException.cs

@@ -17,16 +17,16 @@ namespace PolylineAlgorithm.Diagnostics;
 /// This exception is used internally to indicate that a polyline string does not conform to the expected format or contains errors.
 /// </remarks>
 [DebuggerDisplay($"{nameof(InvalidPolylineException)}: {{ToString()}}")]
-[SuppressMessage("Roslynator", "RCS1194:Implement exception constructors", Justification = "Internal use only.")]
-[SuppressMessage("Design", "CA1032:Implement standard exception constructors", Justification = "Internal use only.")]
+[SuppressMessage("Roslynator", "RCS1194:Implement exception constructors", Justification = "This exception is intended for use by consumers of the library, but additional constructors are not required for its intended usage.")]
+[SuppressMessage("Design", "CA1032:Implement standard exception constructors", Justification = "Standard exception constructors are not necessary for the intended usage of this exception type.")]
 public sealed class InvalidPolylineException : Exception {
     /// <summary>
     /// Initializes a new instance of the <see cref="InvalidPolylineException"/> class with a specified error message.
     /// </summary>
     /// <param name="message">
     /// The error message that describes the reason for the exception.
     /// </param>
-    private InvalidPolylineException(string message)
+    internal InvalidPolylineException(string message)
         : base(message) { }
 
     /// <summary>
@@ -41,6 +41,6 @@ private InvalidPolylineException(string message)
     internal static void Throw(long position) {
         Debug.Assert(position >= 0, "Position must be a non-negative value.");
 
-        throw new InvalidPolylineException(ExceptionMessages.FormatPolylineStringIsMalformed(position));
+        ExceptionGuard.ThrowInvalidPolyline(position);
     }
 }