refactoring, code documentation, clean up

Author: petesramek

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs

@@ -6,7 +6,7 @@
 using System.Buffers;
 
 internal class NetTopologyPolylineDecoder : PolylineDecoder<Point, string> {
-    public override PolylineEncodingOptions<Point> Options { get; } = PolylineEncodingOptions<Point>.Default;
+    public override PolylineEncodingOptions<Point> Options { get; } = new PolylineEncodingOptions<Point>();
 
     protected override Point CreateCoordinate(double latitude, double longitude) {
         return new Point(latitude, longitude);

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs

@@ -6,7 +6,7 @@
 using System.Text;
 
 internal class NetTopologyPolylineEncoder : PolylineEncoder<Point, string> {
-    public override PolylineEncodingOptions<Point> Options { get; } = PolylineEncodingOptions<Point>.Default;
+    public override PolylineEncodingOptions<Point> Options { get; } = new PolylineEncodingOptions<Point>();
 
     protected override string CreatePolyline(ReadOnlySequence<char> sequence) {
         if (sequence.IsEmpty) {

src/PolylineAlgorithm.Abstraction/InvalidPolylineException.cs

@@ -34,7 +34,7 @@ private InvalidPolylineException(string message)
     /// <exception cref="InvalidPolylineException">
     /// Always thrown to indicate that the polyline is malformed at the specified position.
     /// </exception>
-    internal static void Throw(long position) {
+    public static void Throw(long position) {
         throw new InvalidPolylineException(string.Format(ExceptionMessageResource.PolylineStringIsMalformedMessage, position.ToString()));
     }
 }

src/PolylineAlgorithm.Abstraction/PolylineDecoder.cs

@@ -60,16 +60,16 @@ public IEnumerable<TCoordinate> Decode(TPolyline polyline) {
             position = 0;
             sequence = enumerator.Current;
 
-            while (PolylineEncoding.Default.TryReadValue(ref latitude, ref sequence, ref position)
-                && PolylineEncoding.Default.TryReadValue(ref longitude, ref sequence, ref position)
+            while (PolylineEncoding.TryReadValue(ref latitude, ref sequence, ref position)
+                && PolylineEncoding.TryReadValue(ref longitude, ref sequence, ref position)
             ) {
-                coordinate = (PolylineEncoding.Default.Denormalize(latitude), PolylineEncoding.Default.Denormalize(longitude));
+                coordinate = (PolylineEncoding.Denormalize(latitude), PolylineEncoding.Denormalize(longitude));
 
                 if(!Options.Validator.IsValidLatitude(coordinate.Latitude) && !Options.Validator.IsValidLongitude(coordinate.Longitude)) {
                     throw new Exception();
                 }
 
-                yield return CreateCoordinate(PolylineEncoding.Default.Denormalize(latitude), PolylineEncoding.Default.Denormalize(longitude));
+                yield return CreateCoordinate(PolylineEncoding.Denormalize(latitude), PolylineEncoding.Denormalize(longitude));
             }
 
             consumed += position;

src/PolylineAlgorithm.Abstraction/PolylineEncoder.cs

@@ -66,14 +66,14 @@ public TPolyline Encode(IEnumerable<TCoordinate> coordinates) {
 
         while (enumerator.MoveNext()) {
             variance
-                .Next(PolylineEncoding.Default.Normalize(GetLatitude(enumerator.Current)), PolylineEncoding.Default.Normalize(GetLongitude(enumerator.Current)));
+                .Next(PolylineEncoding.Normalize(GetLatitude(enumerator.Current)), PolylineEncoding.Normalize(GetLongitude(enumerator.Current)));
 
             if (GetRemainingBufferSize(position, buffer.Length) < GetRequiredLength(variance)) {
                 throw new InternalBufferOverflowException();
             }
 
-            if (!PolylineEncoding.Default.TryWriteValue(variance.Latitude, ref buffer, ref position)
-                || !PolylineEncoding.Default.TryWriteValue(variance.Longitude, ref buffer, ref position)
+            if (!PolylineEncoding.TryWriteValue(variance.Latitude, ref buffer, ref position)
+                || !PolylineEncoding.TryWriteValue(variance.Longitude, ref buffer, ref position)
             ) {
                 throw new InvalidOperationException();
             }
@@ -91,7 +91,7 @@ public TPolyline Encode(IEnumerable<TCoordinate> coordinates) {
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         static int GetRequiredLength(CoordinateVariance variance) =>
-            PolylineEncoding.Default.GetCharCount(variance.Latitude) + PolylineEncoding.Default.GetCharCount(variance.Longitude);
+            PolylineEncoding.GetCharCount(variance.Latitude) + PolylineEncoding.GetCharCount(variance.Longitude);
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         static int GetRemainingBufferSize(int position, int length) => length - position;

src/PolylineAlgorithm.Abstraction/PolylineEncoding.cs

@@ -13,12 +13,7 @@ namespace PolylineAlgorithm.Abstraction;
 /// Provides methods for encoding and decoding geographic coordinates to and from polyline strings.
 /// Supports normalization, denormalization, and efficient value encoding/decoding for polyline algorithms.
 /// </summary>
-public class PolylineEncoding {
-    /// <summary>
-    /// Gets the default singleton instance of the <see cref="PolylineEncoding"/> class.
-    /// </summary>
-    public static readonly PolylineEncoding Default = new();
-
+public static class PolylineEncoding {
     /// <summary>
     /// Attempts to read an encoded value from the specified buffer and update the provided variance.
     /// </summary>
@@ -35,7 +30,7 @@ public class PolylineEncoding {
     /// <see langword="true"/> if a value was successfully read; otherwise, <see langword="false"/>.
     /// </returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public bool TryReadValue(ref int variance, ref ReadOnlyMemory<char> buffer, ref int position) {
+    public static bool TryReadValue(ref int variance, ref ReadOnlyMemory<char> buffer, ref int position) {
         if (position == buffer.Length) {
             return false;
         }
@@ -70,7 +65,7 @@ public bool TryReadValue(ref int variance, ref ReadOnlyMemory<char> buffer, ref
     /// The denormalized double value.
     /// </returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public double Denormalize(int value) => Math.Truncate((double)value) / Defaults.Algorithm.Precision;
+    public static double Denormalize(int value) => Math.Truncate((double)value) / Defaults.Algorithm.Precision;
 
     /// <summary>
     /// Attempts to write an encoded value to the specified buffer.
@@ -88,7 +83,7 @@ public bool TryReadValue(ref int variance, ref ReadOnlyMemory<char> buffer, ref
     /// <see langword="true"/> if the value was successfully written; otherwise, <see langword="false"/>.
     /// </returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public bool TryWriteValue(int variance, ref Span<char> buffer, ref int position) {
+    public static bool TryWriteValue(int variance, ref Span<char> buffer, ref int position) {
         if (buffer.Length < position + GetCharCount(variance)) {
             return false;
         }
@@ -119,7 +114,7 @@ public bool TryWriteValue(int variance, ref Span<char> buffer, ref int position)
     /// The normalized integer value.
     /// </returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public int Normalize(double value) => (int)Math.Round(value * Defaults.Algorithm.Precision);
+    public static int Normalize(double value) => (int)Math.Round(value * Defaults.Algorithm.Precision);
 
     /// <summary>
     /// Calculates the number of characters required to encode a given variance value.
@@ -131,7 +126,7 @@ public bool TryWriteValue(int variance, ref Span<char> buffer, ref int position)
     /// The number of characters required to encode the variance.
     /// </returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public int GetCharCount(int variance) => variance switch {
+    public static int GetCharCount(int variance) => variance switch {
         // DO NOT CHANGE THE ORDER. We are skipping inside exclusive ranges as those are covered by previous statements.
         >= -16 and <= +15 => 1,
         >= -512 and <= +511 => 2,

src/PolylineAlgorithm.Abstraction/PolylineEncodingOptions.cs

@@ -12,18 +12,30 @@ namespace PolylineAlgorithm.Abstraction;
 /// <summary>
 /// Options for configuring polyline encoding.
 /// </summary>
+/// <typeparam name="TCoordinate">The type representing a coordinate.</typeparam>
 public class PolylineEncodingOptions<TCoordinate> {
-    public static PolylineEncodingOptions<TCoordinate> Default => new();
-
     /// <summary>
     /// Gets the maximum buffer size for encoding operations.
     /// </summary>
     public int MaxBufferSize { get; } = 64_000;
 
-    public CoordinateValidator<TCoordinate> Validator { get; } = new NullValidator<TCoordinate>();
+    /// <summary>
+    /// Gets the validator used to validate coordinates, latitude, and longitude values.
+    /// </summary>
+    public Validator<TCoordinate> Validator { get; } = new NullValidator<TCoordinate>();
 
+    /// <summary>
+    /// Gets the maximum number of characters that can be used in the encoding buffer.
+    /// </summary>
+    /// <returns>The maximum character count based on the buffer size.</returns>
     internal int GetMaxCharCount() => MaxBufferSize / sizeof(char);
 
+    /// <summary>
+    /// Validates the encoding options to ensure they are within acceptable limits.
+    /// </summary>
+    /// <exception cref="ArgumentException">
+    /// Thrown if <see cref="MaxBufferSize"/> is less than the minimum required buffer size.
+    /// </exception>
     internal void Validate() {
         if (MaxBufferSize < Defaults.Polyline.MaxEncodedCoordinateLength * sizeof(char)) {
             throw new ArgumentException();

src/PolylineAlgorithm.Abstraction/Validation/Abstraction/CoordinateValidator.cs

@@ -0,0 +1,33 @@
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Abstraction.Validation.Abstraction;
+
+/// <summary>
+/// Provides an abstract base class for validating coordinates and their latitude/longitude components.
+/// </summary>
+/// <typeparam name="TCoordinate">The type representing a coordinate.</typeparam>
+public abstract class Validator<TCoordinate> {
+    /// <summary>
+    /// Determines whether the specified coordinate is valid.
+    /// </summary>
+    /// <param name="coordinate">The coordinate to validate.</param>
+    /// <returns><see langword="true"/> if the coordinate is valid; otherwise, <see langword="false"/>.</returns>
+    public abstract bool IsValid(TCoordinate coordinate);
+
+    /// <summary>
+    /// Determines whether the specified latitude value is valid.
+    /// </summary>
+    /// <param name="latitude">The latitude value to validate.</param>
+    /// <returns><see langword="true"/> if the latitude is valid; otherwise, <see langword="false"/>.</returns>
+    public abstract bool IsValidLatitude(double latitude);
+
+    /// <summary>
+    /// Determines whether the specified longitude value is valid.
+    /// </summary>
+    /// <param name="longitude">The longitude value to validate.</param>
+    /// <returns><see langword="true"/> if the longitude is valid; otherwise, <see langword="false"/>.</returns>
+    public abstract bool IsValidLongitude(double longitude);
+}

src/PolylineAlgorithm.Abstraction/Validation/Abstraction/Validator.cs

@@ -2,15 +2,23 @@
 
 using PolylineAlgorithm.Abstraction.Validation.Abstraction;
 
-public sealed class NullValidator<TCoordinate> : CoordinateValidator<TCoordinate> {
+
+/// <summary>
+/// A validator that always returns <see langword="true"/> for any coordinate, latitude, or longitude.
+/// </summary>
+/// <typeparam name="TCoordinate">The type representing a coordinate.</typeparam>
+public sealed class NullValidator<TCoordinate> : Validator<TCoordinate> {
+    /// <inheritdoc/>
     public override bool IsValid(TCoordinate coordinate) {
         return true;
     }
 
+    /// <inheritdoc/>
     public override bool IsValidLatitude(double latitude) {
         return true;
     }
 
+    /// <inheritdoc/>
     public override bool IsValidLongitude(double longitude) {
         return true;
     }