PolylineAlgorithm.Abstraction.IPolylineEncoder-2.yml

### YamlMime:ApiPage
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/copilot/review-github-templates/src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs#L36
  metadata:
    uid: PolylineAlgorithm.Abstraction.IPolylineEncoder`2
    commentId: T:PolylineAlgorithm.Abstraction.IPolylineEncoder`2
- facts:
  - name: Namespace
    value:
      text: PolylineAlgorithm.Abstraction
      url: PolylineAlgorithm.Abstraction.html
  - name: Assembly
    value: PolylineAlgorithm.dll
- markdown: >-
    Contract for encoding a sequence of geographic coordinates into an encoded polyline representation.

    Implementations interpret the generic <code class="typeparamref">TValue</code> type and produce an encoded

    representation of those coordinates as <code class="typeparamref">TPolyline</code>.
- code: public interface IPolylineEncoder<TValue, TPolyline>
- h4: Type Parameters
- parameters:
  - name: TValue
    description: >-
      The concrete coordinate representation used by the encoder (for example a struct or class containing

      <code>Latitude</code> and <code>Longitude</code> values). Implementations must document the expected shape,

      units (typically decimal degrees), and any required fields for <code class="typeparamref">TValue</code>.

      Common shapes:

      - A struct or class with two <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/floating-point-numeric-types">double</a> properties named <code>Latitude</code> and <code>Longitude</code>.

      - A tuple-like type (for example <code>ValueTuple&lt;double,double&gt;</code>) where the encoder documents
        which element represents latitude and longitude.
  - name: TPolyline
    description: >-
      The encoded polyline representation returned by the encoder (for example <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/reference-types">string</a>,

      <code>ReadOnlyMemory&lt;char&gt;</code>, or a custom wrapper type). Concrete implementations should document

      the chosen representation and any memory / ownership expectations.
- h4: Extension Methods
- list:
  - text: PolylineEncoderExtensions.Encode<TValue, TPolyline>(IPolylineEncoder<TValue, TPolyline>, List<TValue>)
    url: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.html#PolylineAlgorithm_Extensions_PolylineEncoderExtensions_Encode__2_PolylineAlgorithm_Abstraction_IPolylineEncoder___0___1__System_Collections_Generic_List___0__
  - text: PolylineEncoderExtensions.Encode<TValue, TPolyline>(IPolylineEncoder<TValue, TPolyline>, TValue[])
    url: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.html#PolylineAlgorithm_Extensions_PolylineEncoderExtensions_Encode__2_PolylineAlgorithm_Abstraction_IPolylineEncoder___0___1____0___
- h2: Remarks
- markdown: >-
    - This interface is intentionally minimal to allow different encoding strategies (Google encoded polyline,
      precision/scale variants, or custom compressed formats) to be expressed behind a common contract.
    - Implementations should document:
      - Coordinate precision and rounding rules (for example 1e-5 for 5-decimal precision).
      - Coordinate 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>, CancellationToken)
  id: PolylineAlgorithm_Abstraction_IPolylineEncoder_2_Encode_System_ReadOnlySpan__0__System_Threading_CancellationToken_
  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/copilot/review-github-templates/src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs#L76
  metadata:
    uid: PolylineAlgorithm.Abstraction.IPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},System.Threading.CancellationToken)
    commentId: M:PolylineAlgorithm.Abstraction.IPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},System.Threading.CancellationToken)
- markdown: >-
    Encodes a sequence of geographic coordinates into an encoded polyline representation.

    The order of coordinates in <code class="paramref">coordinates</code> is preserved in the encoded result.
- code: TPolyline Encode(ReadOnlySpan<TValue> coordinates, CancellationToken cancellationToken = default)
- h4: Parameters
- parameters:
  - name: coordinates
    type:
    - text: ReadOnlySpan
      url: https://learn.microsoft.com/dotnet/api/system.readonlyspan-1
    - <
    - TValue
    - '>'
    description: >-
      The collection 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

      (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>.
  - name: cancellationToken
    type:
    - text: CancellationToken
      url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken
    description: >-
      A <xref href="System.Threading.CancellationToken" data-throw-if-not-resolved="false"></xref> that can be used to cancel the encoding operation.

      Implementations should observe this token and throw <xref href="System.OperationCanceledException" data-throw-if-not-resolved="false"></xref>

      when cancellation is requested. For fast, in-memory encoders cancellation may be best-effort.
    optional: true
- h4: Returns
- parameters:
  - type:
    - TPolyline
    description: >-
      A <code class="typeparamref">TPolyline</code> containing the encoded polyline that represents the input coordinates.

      The exact format and any delimiting/terminating characters are implementation-specific and must be

      documented by concrete encoder types.
- h4: Examples
- markdown: >-
    <pre><code class="lang-csharp">// Example pseudocode for typical usage with a string-based encoder:

    var coords = new[] {
        new Coordinate { Latitude = 47.6219, Longitude = -122.3503 },
        new Coordinate { Latitude = 47.6220, Longitude = -122.3504 }
    };

    IPolylineEncoder&lt;Coordinate,string&gt; encoder = new GoogleEncodedPolylineEncoder();

    string encoded = encoder.Encode(coords, CancellationToken.None);</code></pre>
- h4: Remarks
- markdown: >-
    - Implementations should validate input as appropriate and document any preconditions (for example
      if coordinates must be within [-90,90] latitude and [-180,180] longitude).
    - For large input sequences, implementations may provide streaming or incremental encoders; those
      variants can still implement this interface by materializing the final encoded result.
- h4: Exceptions
- parameters:
  - type:
    - text: OperationCanceledException
      url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception
    description: Thrown if the operation is canceled via <code class="paramref">cancellationToken</code>.
languageId: csharp
metadata:
  description: >-
    Contract for encoding a sequence of geographic coordinates into an encoded polyline representation.

    Implementations interpret the generic TValue type and produce an encoded

    representation of those coordinates as TPolyline.