interim commit

Author: petesramek

benchmarks/PolylineAlgorithm.Benchmarks/PolylineBuilderBenchmark.cs

@@ -6,9 +6,7 @@
 namespace PolylineAlgorithm.Benchmarks;
 
 using BenchmarkDotNet.Attributes;
-using PolylineAlgorithm;
 using PolylineAlgorithm.Abstraction.Internal;
-using PolylineAlgorithm.Internal;
 using PolylineAlgorithm.Utility;
 using System.Buffers;
 

benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncoderBenchmark.cs

@@ -7,7 +7,6 @@ namespace PolylineAlgorithm.Benchmarks;
 
 using BenchmarkDotNet.Attributes;
 using PolylineAlgorithm;
-using PolylineAlgorithm.Abstraction;
 using PolylineAlgorithm.Utility;
 using System.Collections.Generic;
 

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs

@@ -6,12 +6,14 @@
 using System.Buffers;
 
 internal class NetTopologyPolylineDecoder : PolylineDecoder<Point, string> {
+    public override PolylineEncodingOptions<Point> Options { get; } = PolylineEncodingOptions<Point>.Default;
+
     protected override Point CreateCoordinate(double latitude, double longitude) {
         return new Point(latitude, longitude);
     }
 
     protected override ReadOnlySequence<char> GetReadOnlySequence(string? polyline) {
-        if(string.IsNullOrWhiteSpace(polyline)) {
+        if (string.IsNullOrWhiteSpace(polyline)) {
             throw new ArgumentException("Value cannot be null, empty or whitespace.", nameof(polyline));
         }
 

samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs

@@ -2,17 +2,18 @@
 
 using global::NetTopologySuite.Geometries;
 using PolylineAlgorithm.Abstraction;
-using System;
 using System.Buffers;
 using System.Text;
 
 internal class NetTopologyPolylineEncoder : PolylineEncoder<Point, string> {
+    public override PolylineEncodingOptions<Point> Options { get; } = PolylineEncodingOptions<Point>.Default;
+
     protected override string CreatePolyline(ReadOnlySequence<char> sequence) {
-        if(sequence.IsEmpty) {
+        if (sequence.IsEmpty) {
             return string.Empty;
         }
 
-        if(sequence.IsSingleSegment) {
+        if (sequence.IsSingleSegment) {
             return sequence.FirstSpan.ToString();
         }
 

src/PolylineAlgorithm.Abstraction/IPolylineDecoder.cs

@@ -15,10 +15,10 @@ public interface IPolylineDecoder<TCoordinate, TPolyline> {
     /// Decodes the specified encoded polyline into a sequence of geographic coordinates.
     /// </summary>
     /// <param name="polyline">
-    /// The <see cref="Polyline"/> instance containing the encoded polyline string to decode.
+    /// The <typeparamref name="TPolyline"/> instance containing the encoded polyline string to decode.
     /// </param>
     /// <returns>
-    /// An <see cref="IEnumerable{T}"/> of <see cref="Coordinate"/> representing the decoded latitude and longitude pairs.
+    /// An <see cref="IEnumerable{T}"/> of <typeparamref name="TCoordinate"/> representing the decoded latitude and longitude pairs.
     /// </returns>
-    IEnumerable<TCoordinate> Decode(TPolyline coordinates);
+    IEnumerable<TCoordinate> Decode(TPolyline polyline);
 }

src/PolylineAlgorithm.Abstraction/IPolylineEncoder.cs

@@ -15,10 +15,10 @@ public interface IPolylineEncoder<TCoordinate, TPolyline> {
     /// Encodes a sequence of geographic coordinates into an encoded polyline representation.
     /// </summary>
     /// <param name="coordinates">
-    /// The collection of <see cref="Coordinate"/> instances to encode into a polyline.
+    /// The collection of <typeparamref name="TCoordinate"/> instances to encode into a polyline.
     /// </param>
     /// <returns>
-    /// A <see cref="Polyline"/> containing the encoded polyline string that represents the input coordinates.
+    /// A <typeparamref name="TPolyline"/> containing the encoded polyline string that represents the input coordinates.
     /// </returns>
     TPolyline Encode(IEnumerable<TCoordinate> coordinates);
 }

src/PolylineAlgorithm.Abstraction/Internal/PolylineBuilder.cs

@@ -10,7 +10,7 @@ namespace PolylineAlgorithm.Abstraction.Internal;
 using System.Runtime.InteropServices;
 
 /// <summary>
-/// Provides an efficient mechanism for constructing a <see cref="Polyline"/> from multiple character segments.
+/// Provides an efficient mechanism for constructing a <see cref="ReadOnlySequence{T}"/> from multiple character segments.
 /// This struct enables incremental building of a polyline by appending segments and producing a single concatenated result.
 /// </summary>
 [StructLayout(LayoutKind.Auto)]
@@ -37,13 +37,13 @@ public void Append(ReadOnlyMemory<char> value) {
     }
 
     /// <summary>
-    /// Constructs the final <see cref="Polyline"/> instance by concatenating all appended segments.
+    /// Constructs a <see cref="ReadOnlySequence{T}"/> representing the concatenation of all appended character segments.
     /// </summary>
     /// <returns>
-    /// A <see cref="Polyline"/> representing the combined character segments.
-    /// If no segments have been appended, returns an empty <see cref="Polyline"/>.
+    /// A <see cref="ReadOnlySequence{T}"/> containing all segments appended to this builder, or an empty sequence if no segments were added.
     /// </returns>
-    public readonly ReadOnlySequence<char> Build() {
+    public readonly ReadOnlySequence<char> Build()
+    {
         if (_initial is null) {
             return new();
         }

src/PolylineAlgorithm.Abstraction/Internal/PolylineSegment.cs

@@ -9,14 +9,14 @@ namespace PolylineAlgorithm.Abstraction.Internal;
 
 /// <summary>
 /// Represents a segment of a polyline as part of a linked list of character memory segments.
-/// Inherits from <see cref="ReadOnlySequenceSegment{char}"/> to enable efficient manipulation and traversal of polyline data.
+/// Inherits from <see cref="ReadOnlySequenceSegment{T}"/> to enable efficient manipulation and traversal of polyline data.
 /// </summary>
 internal class PolylineSegment : ReadOnlySequenceSegment<char> {
     /// <summary>
     /// Initializes a new instance of the <see cref="PolylineSegment"/> class with the specified memory segment and optional running index.
     /// </summary>
     /// <param name="memory">
-    /// The <see cref="ReadOnlyMemory{char}"/> segment to associate with this polyline segment.
+    /// The <see cref="ReadOnlyMemory{T}"/> segment to associate with this polyline segment.
     /// </param>
     /// <param name="runningIndex">
     /// The cumulative index of this segment within the polyline sequence. Defaults to 0.
@@ -30,7 +30,7 @@ public PolylineSegment(ReadOnlyMemory<char> memory, long runningIndex = 0) {
     /// Appends a new memory segment to the end of the current polyline segment chain.
     /// </summary>
     /// <param name="memory">
-    /// The <see cref="ReadOnlyMemory{char}"/> segment to append as a new <see cref="PolylineSegment"/>.
+    /// The <see cref="ReadOnlyMemory{T}"/> segment to append as a new <see cref="PolylineSegment"/>.
     /// </param>
     public void Append(ReadOnlyMemory<char> memory) {
         Append(new PolylineSegment(memory));

src/PolylineAlgorithm.Abstraction/PolylineAlgorithm.Abstraction.csproj

@@ -39,25 +39,22 @@
 		<Copyright>© 2025, Pete Sramek.</Copyright>
 	</PropertyGroup>
 
+	<ItemGroup>
+	  <AdditionalFiles Include="PublicAPI.Shipped.txt" />
+	  <AdditionalFiles Include="PublicAPI.Unshipped.txt" />
+	</ItemGroup>
+
 	<ItemGroup>
 		<PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="3.*">
 			<PrivateAssets>all</PrivateAssets>
 			<IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
 		</PackageReference>
 	</ItemGroup>
 
-	<ItemGroup>
-	  <Compile Update="Properties\ExceptionMessageResource.Designer.cs">
-	    <DependentUpon>ExceptionMessageResource.resx</DependentUpon>
-	    <DesignTime>True</DesignTime>
-	    <AutoGen>True</AutoGen>
-	  </Compile>
-	</ItemGroup>
-
 	<ItemGroup>
 	  <EmbeddedResource Update="Properties\ExceptionMessageResource.resx">
-	    <LastGenOutput>ExceptionMessageResource.Designer.cs</LastGenOutput>
 	    <Generator>ResXFileCodeGenerator</Generator>
+	    <LastGenOutput>ExceptionMessageResource.Designer.cs</LastGenOutput>
 	  </EmbeddedResource>
 	</ItemGroup>
 
@@ -70,4 +67,19 @@
 		</AssemblyAttribute>
 	</ItemGroup>
 
+	<ItemGroup>
+	  <None Include="..\..\README.md" Link="README.md">
+	    <PackagePath>\</PackagePath>
+	    <Pack>True</Pack>
+	  </None>
+	</ItemGroup>
+
+	<ItemGroup>
+	  <Compile Update="Properties\ExceptionMessageResource.Designer.cs">
+	    <DesignTime>True</DesignTime>
+	    <AutoGen>True</AutoGen>
+	    <DependentUpon>ExceptionMessageResource.resx</DependentUpon>
+	  </Compile>
+	</ItemGroup>
+
 </Project>

src/PolylineAlgorithm.Abstraction/PolylineDecoder.cs

@@ -12,17 +12,22 @@ namespace PolylineAlgorithm.Abstraction;
 
 /// <summary>
 /// Decodes encoded polyline strings into sequences of geographic coordinates.
-/// Implements the <see cref="IPolylineDecoder"/> interface.
+/// Implements the <see cref="IPolylineDecoder{TCoordinate, TPolyline}"/> interface.
 /// </summary>
 public abstract class PolylineDecoder<TCoordinate, TPolyline> : IPolylineDecoder<TCoordinate, TPolyline> {
     /// <summary>
-    /// Decodes an encoded <see cref="Polyline"/> into a sequence of <see cref="Coordinate"/> instances.
+    /// Gets the encoding options used by this polyline encoder.
+    /// </summary>
+    public abstract PolylineEncodingOptions<TCoordinate> Options { get; }
+
+    /// <summary>
+    /// Decodes an encoded <typeparamref name="TPolyline"/> into a sequence of <typeparamref name="TCoordinate"/> instances.
     /// </summary>
     /// <param name="polyline">
-    /// The <see cref="Polyline"/> instance containing the encoded polyline string to decode.
+    /// The <typeparamref name="TPolyline"/> instance containing the encoded polyline string to decode.
     /// </param>
     /// <returns>
-    /// An <see cref="IEnumerable{T}"/> of <see cref="Coordinate"/> representing the decoded latitude and longitude pairs.
+    /// An <see cref="IEnumerable{T}"/> of <typeparamref name="TCoordinate"/> representing the decoded latitude and longitude pairs.
     /// </returns>
     /// <exception cref="ArgumentException">
     /// Thrown when <paramref name="polyline"/> is empty.
@@ -38,14 +43,15 @@ public IEnumerable<TCoordinate> Decode(TPolyline polyline) {
         ReadOnlySequence<char> source = GetReadOnlySequence(polyline);
 
         if (source.Length < Defaults.Polyline.MinEncodedCoordinateLength) {
-            throw new ArgumentException(ExceptionMessageResource.ArgumentCannotBeNullEmptyOrWhitespaceMessage, nameof(polyline));
+            throw new ArgumentException(string.Format(ExceptionMessageResource.PolylineCannotBeShorterThanExceptionMessage, source.Length), nameof(polyline));
         }
 
         ReadOnlySequence<char>.Enumerator enumerator = source.GetEnumerator();
 
         int consumed = 0;
         int latitude = 0;
         int longitude = 0;
+        (double Latitude, double Longitude) coordinate;
 
         int position;
         ReadOnlyMemory<char> sequence;
@@ -57,6 +63,12 @@ public IEnumerable<TCoordinate> Decode(TPolyline polyline) {
             while (PolylineEncoding.Default.TryReadValue(ref latitude, ref sequence, ref position)
                 && PolylineEncoding.Default.TryReadValue(ref longitude, ref sequence, ref position)
             ) {
+                coordinate = (PolylineEncoding.Default.Denormalize(latitude), PolylineEncoding.Default.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));
             }
 
@@ -68,7 +80,22 @@ public IEnumerable<TCoordinate> Decode(TPolyline polyline) {
         }
     }
 
+    /// <summary>
+    /// Converts the provided polyline instance into a <see cref="ReadOnlySequence{Char}"/> for decoding.
+    /// </summary>
+    /// <param name="polyline">
+    /// The polyline instance to convert. May be <c>null</c>.
+    /// </param>
+    /// <returns>
+    /// A <see cref="ReadOnlySequence{T}"/> representing the encoded polyline data.
+    /// </returns>
     protected abstract ReadOnlySequence<char> GetReadOnlySequence(TPolyline? polyline);
 
+    /// <summary>
+    /// Creates a coordinate instance from the given latitude and longitude values.
+    /// </summary>
+    /// <param name="latitude">The latitude value.</param>
+    /// <param name="longitude">The longitude value.</param>
+    /// <returns>A coordinate instance of type <typeparamref name="TCoordinate"/>.</returns>
     protected abstract TCoordinate CreateCoordinate(double latitude, double longitude);
 }