Merge branch 'extend-polylinealgorithm-multi-dimensional-support' of https://github.com/petesramek/polyline-algorithm-csharp into extend-polylinealgorithm-multi-dimensional-support

Author: petesramek

api-reference/0.0/PolylineAlgorithm.Abstraction.IPolylineEncoder-2.yml

@@ -3,7 +3,7 @@ title: Interface IPolylineEncoder<TValue, TPolyline>
 body:
 - api1: Interface IPolylineEncoder<TValue, TPolyline>
   id: PolylineAlgorithm_Abstraction_IPolylineEncoder_2
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs#L36
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs#L38
   metadata:
     uid: PolylineAlgorithm.Abstraction.IPolylineEncoder`2
     commentId: T:PolylineAlgorithm.Abstraction.IPolylineEncoder`2
@@ -56,35 +56,35 @@ body:
       - Value precision and rounding rules (for example 1e-5 for 5-decimal precision).
       - Value ordering and whether altitude or additional dimensions are supported.
       - Thread-safety guarantees: whether instances are safe to reuse concurrently or must be instantiated per-call.
-    - Implementations are encouraged to be memory-efficient; the API accepts a <xref href="System.ReadOnlySpan%601" data-throw-if-not-resolved="false"></xref>
-      to avoid forced allocations when callers already have contiguous memory.
 - h2: Methods
-- api3: Encode(ReadOnlySpan<TValue>, PolylineEncodingOptions<TValue>?, CancellationToken)
-  id: PolylineAlgorithm_Abstraction_IPolylineEncoder_2_Encode_System_ReadOnlySpan__0__PolylineAlgorithm_PolylineEncodingOptions__0__System_Threading_CancellationToken_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs#L76
+- api3: Encode(IEnumerable<TValue>, PolylineEncodingOptions<TValue>?, CancellationToken)
+  id: PolylineAlgorithm_Abstraction_IPolylineEncoder_2_Encode_System_Collections_Generic_IEnumerable__0__PolylineAlgorithm_PolylineEncodingOptions__0__System_Threading_CancellationToken_
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs#L82
   metadata:
-    uid: PolylineAlgorithm.Abstraction.IPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
-    commentId: M:PolylineAlgorithm.Abstraction.IPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
+    uid: PolylineAlgorithm.Abstraction.IPolylineEncoder`2.Encode(System.Collections.Generic.IEnumerable{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
+    commentId: M:PolylineAlgorithm.Abstraction.IPolylineEncoder`2.Encode(System.Collections.Generic.IEnumerable{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
 - markdown: >-
     Encodes a sequence of values into an encoded polyline representation.
 
     The order of values in <code class="paramref">coordinates</code> is preserved in the encoded result.
-- code: TPolyline Encode(ReadOnlySpan<TValue> coordinates, PolylineEncodingOptions<TValue>? options = null, CancellationToken cancellationToken = default)
+- code: TPolyline Encode(IEnumerable<TValue> coordinates, PolylineEncodingOptions<TValue>? options = null, CancellationToken cancellationToken = default)
 - h4: Parameters
 - parameters:
   - name: coordinates
     type:
-    - text: ReadOnlySpan
-      url: https://learn.microsoft.com/dotnet/api/system.readonlyspan-1
+    - text: IEnumerable
+      url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1
     - <
     - TValue
     - '>'
     description: >-
-      The collection of <code class="typeparamref">TValue</code> instances to encode into a polyline.
+      The sequence of <code class="typeparamref">TValue</code> instances to encode into a polyline.
 
-      The span may be empty; implementations should return an appropriate empty encoded representation
+      The sequence may be empty; implementations should return an appropriate empty encoded representation
 
       (for example an empty string or an empty memory slice) rather than <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null">null</a>.
+
+      Must not be <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null">null</a>.
   - name: options
     type:
     - text: PolylineEncodingOptions
@@ -135,6 +135,10 @@ body:
       variants can still implement this interface by materializing the final encoded result.
 - h4: Exceptions
 - parameters:
+  - type:
+    - text: ArgumentNullException
+      url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception
+    description: Thrown if <code class="paramref">coordinates</code> is <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null">null</a>.
   - type:
     - text: OperationCanceledException
       url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception

api-reference/0.0/PolylineAlgorithm.Extensions.PolylineEncoderExtensions.yml

@@ -3,7 +3,7 @@ title: Class PolylineEncoderExtensions
 body:
 - api1: Class PolylineEncoderExtensions
   id: PolylineAlgorithm_Extensions_PolylineEncoderExtensions
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs#L15
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs#L16
   metadata:
     uid: PolylineAlgorithm.Extensions.PolylineEncoderExtensions
     commentId: T:PolylineAlgorithm.Extensions.PolylineEncoderExtensions
@@ -41,7 +41,7 @@ body:
 - h2: Methods
 - api3: Encode<TValue, TPolyline>(IPolylineEncoder<TValue, TPolyline>, TValue[], PolylineEncodingOptions<TValue>?, CancellationToken)
   id: PolylineAlgorithm_Extensions_PolylineEncoderExtensions_Encode__2_PolylineAlgorithm_Abstraction_IPolylineEncoder___0___1____0___PolylineAlgorithm_PolylineEncodingOptions___0__System_Threading_CancellationToken_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs#L33
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs#L34
   metadata:
     uid: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.Encode``2(PolylineAlgorithm.Abstraction.IPolylineEncoder{``0,``1},``0[],PolylineAlgorithm.PolylineEncodingOptions{``0},System.Threading.CancellationToken)
     commentId: M:PolylineAlgorithm.Extensions.PolylineEncoderExtensions.Encode``2(PolylineAlgorithm.Abstraction.IPolylineEncoder{``0,``1},``0[],PolylineAlgorithm.PolylineEncodingOptions{``0},System.Threading.CancellationToken)

api-reference/0.0/PolylineAlgorithm.PolylineEncoder-2.yml

@@ -3,7 +3,7 @@ title: Class PolylineEncoder<TValue, TPolyline>
 body:
 - api1: Class PolylineEncoder<TValue, TPolyline>
   id: PolylineAlgorithm_PolylineEncoder_2
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/PolylineEncoder.cs#L28
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/PolylineEncoder.cs#L26
   metadata:
     uid: PolylineAlgorithm.PolylineEncoder`2
     commentId: T:PolylineAlgorithm.PolylineEncoder`2
@@ -62,7 +62,7 @@ body:
 - h2: Constructors
 - api3: PolylineEncoder(PolylineOptions<TValue, TPolyline>)
   id: PolylineAlgorithm_PolylineEncoder_2__ctor_PolylineAlgorithm_PolylineOptions__0__1__
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/PolylineEncoder.cs#L43
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/PolylineEncoder.cs#L41
   metadata:
     uid: PolylineAlgorithm.PolylineEncoder`2.#ctor(PolylineAlgorithm.PolylineOptions{`0,`1})
     commentId: M:PolylineAlgorithm.PolylineEncoder`2.#ctor(PolylineAlgorithm.PolylineOptions{`0,`1})
@@ -94,23 +94,26 @@ body:
       url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception
     description: Thrown when <code class="paramref">options</code> is <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null">null</a>.
 - h2: Methods
-- api3: Encode(ReadOnlySpan<TValue>, CancellationToken)
-  id: PolylineAlgorithm_PolylineEncoder_2_Encode_System_ReadOnlySpan__0__System_Threading_CancellationToken_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/PolylineEncoder.cs#L72
+- api3: Encode(IEnumerable<TValue>, CancellationToken)
+  id: PolylineAlgorithm_PolylineEncoder_2_Encode_System_Collections_Generic_IEnumerable__0__System_Threading_CancellationToken_
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/PolylineEncoder.cs#L70
   metadata:
-    uid: PolylineAlgorithm.PolylineEncoder`2.Encode(System.ReadOnlySpan{`0},System.Threading.CancellationToken)
-    commentId: M:PolylineAlgorithm.PolylineEncoder`2.Encode(System.ReadOnlySpan{`0},System.Threading.CancellationToken)
+    uid: PolylineAlgorithm.PolylineEncoder`2.Encode(System.Collections.Generic.IEnumerable{`0},System.Threading.CancellationToken)
+    commentId: M:PolylineAlgorithm.PolylineEncoder`2.Encode(System.Collections.Generic.IEnumerable{`0},System.Threading.CancellationToken)
 - markdown: >-
     Encodes a collection of <code class="typeparamref">TValue</code> instances into an encoded
 
     <code class="typeparamref">TPolyline</code>.
-- code: public TPolyline Encode(ReadOnlySpan<TValue> coordinates, CancellationToken cancellationToken = default)
+- code: >-
+    [SuppressMessage("Design", "CA1062:Validate arguments of public methods", Justification = "Null is verified before use via ExceptionGuard.ThrowArgumentNull, which is annotated [DoesNotReturn]. CA1062 does not recognise custom [DoesNotReturn] helpers as null guards.")]
+
+    public TPolyline Encode(IEnumerable<TValue> coordinates, CancellationToken cancellationToken = default)
 - h4: Parameters
 - parameters:
   - name: coordinates
     type:
-    - text: ReadOnlySpan
-      url: https://learn.microsoft.com/dotnet/api/system.readonlyspan-1
+    - text: IEnumerable
+      url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1
     - <
     - TValue
     - '>'
@@ -128,24 +131,24 @@ body:
     description: An instance of <code class="typeparamref">TPolyline</code> representing the encoded values.
 - h4: Exceptions
 - parameters:
+  - type:
+    - text: ArgumentNullException
+      url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception
+    description: Thrown when <code class="paramref">coordinates</code> is <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null">null</a>.
   - type:
     - text: ArgumentException
       url: https://learn.microsoft.com/dotnet/api/system.argumentexception
     description: Thrown when <code class="paramref">coordinates</code> is empty.
-  - type:
-    - text: InvalidOperationException
-      url: https://learn.microsoft.com/dotnet/api/system.invalidoperationexception
-    description: Thrown when the internal encoding buffer cannot accommodate the encoded value.
   - type:
     - text: OperationCanceledException
       url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception
     description: Thrown when <code class="paramref">cancellationToken</code> is canceled.
-- api3: Encode(ReadOnlySpan<TValue>, PolylineEncodingOptions<TValue>?, CancellationToken)
-  id: PolylineAlgorithm_PolylineEncoder_2_Encode_System_ReadOnlySpan__0__PolylineAlgorithm_PolylineEncodingOptions__0__System_Threading_CancellationToken_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/PolylineEncoder.cs#L158
+- api3: Encode(IEnumerable<TValue>, PolylineEncodingOptions<TValue>?, CancellationToken)
+  id: PolylineAlgorithm_PolylineEncoder_2_Encode_System_Collections_Generic_IEnumerable__0__PolylineAlgorithm_PolylineEncodingOptions__0__System_Threading_CancellationToken_
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/PolylineEncoder.cs#L107
   metadata:
-    uid: PolylineAlgorithm.PolylineEncoder`2.Encode(System.ReadOnlySpan{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
-    commentId: M:PolylineAlgorithm.PolylineEncoder`2.Encode(System.ReadOnlySpan{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
+    uid: PolylineAlgorithm.PolylineEncoder`2.Encode(System.Collections.Generic.IEnumerable{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
+    commentId: M:PolylineAlgorithm.PolylineEncoder`2.Encode(System.Collections.Generic.IEnumerable{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
 - markdown: >-
     Encodes a collection of <code class="typeparamref">TValue</code> instances into an encoded
 
@@ -154,13 +157,16 @@ body:
     delta baseline. Use this overload to encode large sequences in independent chunks that can be
 
     concatenated into a single valid polyline.
-- code: public TPolyline Encode(ReadOnlySpan<TValue> coordinates, PolylineEncodingOptions<TValue>? options, CancellationToken cancellationToken)
+- code: >-
+    [SuppressMessage("Design", "CA1062:Validate arguments of public methods", Justification = "Null is verified before use via ExceptionGuard.ThrowArgumentNull, which is annotated [DoesNotReturn]. CA1062 does not recognise custom [DoesNotReturn] helpers as null guards.")]
+
+    public TPolyline Encode(IEnumerable<TValue> coordinates, PolylineEncodingOptions<TValue>? options, CancellationToken cancellationToken)
 - h4: Parameters
 - parameters:
   - name: coordinates
     type:
-    - text: ReadOnlySpan
-      url: https://learn.microsoft.com/dotnet/api/system.readonlyspan-1
+    - text: IEnumerable
+      url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1
     - <
     - TValue
     - '>'
@@ -180,7 +186,7 @@ body:
 
       <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null">null</a> to use the formatter's default baseline (same as calling
 
-      <xref href="PolylineAlgorithm.PolylineEncoder%602.Encode(System.ReadOnlySpan%7b%600%7d%2cSystem.Threading.CancellationToken)" data-throw-if-not-resolved="false"></xref>).
+      <xref href="PolylineAlgorithm.PolylineEncoder%602.Encode(System.Collections.Generic.IEnumerable%7b%600%7d%2cSystem.Threading.CancellationToken)" data-throw-if-not-resolved="false"></xref>).
   - name: cancellationToken
     type:
     - text: CancellationToken
@@ -193,14 +199,14 @@ body:
     description: An instance of <code class="typeparamref">TPolyline</code> representing the encoded values.
 - h4: Exceptions
 - parameters:
+  - type:
+    - text: ArgumentNullException
+      url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception
+    description: Thrown when <code class="paramref">coordinates</code> is <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null">null</a>.
   - type:
     - text: ArgumentException
       url: https://learn.microsoft.com/dotnet/api/system.argumentexception
     description: Thrown when <code class="paramref">coordinates</code> is empty.
-  - type:
-    - text: InvalidOperationException
-      url: https://learn.microsoft.com/dotnet/api/system.invalidoperationexception
-    description: Thrown when the internal encoding buffer cannot accommodate the encoded value.
   - type:
     - text: OperationCanceledException
       url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception

api-reference/0.0/PolylineAlgorithm.PolylineEncodingOptions-1.yml

@@ -44,7 +44,7 @@ body:
 - markdown: >-
     Pass an instance of this class to the chunked
 
-    <xref href="PolylineAlgorithm.Abstraction.IPolylineEncoder%602.Encode(System.ReadOnlySpan%7b%600%7d%2cPolylineAlgorithm.PolylineEncodingOptions%7b%600%7d%2cSystem.Threading.CancellationToken)" data-throw-if-not-resolved="false"></xref> overload to control
+    <xref href="PolylineAlgorithm.Abstraction.IPolylineEncoder%602.Encode(System.Collections.Generic.IEnumerable%7b%600%7d%2cPolylineAlgorithm.PolylineEncodingOptions%7b%600%7d%2cSystem.Threading.CancellationToken)" data-throw-if-not-resolved="false"></xref> overload to control
 
     the delta baseline used at the start of each chunk. When <xref href="PolylineAlgorithm.PolylineEncodingOptions%601.HasPrevious" data-throw-if-not-resolved="false"></xref> is