Table of Contents

Interface IPolylineEncoder<TValue, TPolyline>

Namespace
PolylineAlgorithm.Abstraction
Assembly
PolylineAlgorithm.dll

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.

public interface IPolylineEncoder<TValue, TPolyline>

Type Parameters

TValue

The concrete coordinate representation used by the encoder (for example a struct or class containing Latitude and Longitude values). Implementations must document the expected shape, units (typically decimal degrees), and any required fields for TValue. Common shapes:

  • A struct or class with two double properties named Latitude and Longitude.
  • A tuple-like type (for example ValueTuple<double,double>) where the encoder documents which element represents latitude and longitude.
TPolyline

The encoded polyline representation returned by the encoder (for example string, ReadOnlyMemory<char>, or a custom wrapper type). Concrete implementations should document the chosen representation and any memory / ownership expectations.

Extension Methods

Remarks

  • 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 ReadOnlySpan<T> to avoid forced allocations when callers already have contiguous memory.

Methods

Encode(ReadOnlySpan<TValue>, CancellationToken)

Encodes a sequence of geographic coordinates into an encoded polyline representation. The order of coordinates in coordinates is preserved in the encoded result.

TPolyline Encode(ReadOnlySpan<TValue> coordinates, CancellationToken cancellationToken = default)

Parameters

coordinates ReadOnlySpan<TValue>

The collection of TValue 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 null.

cancellationToken CancellationToken

A CancellationToken that can be used to cancel the encoding operation. Implementations should observe this token and throw OperationCanceledException when cancellation is requested. For fast, in-memory encoders cancellation may be best-effort.

Returns

TPolyline

A TPolyline 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.

Examples

// 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<Coordinate,string> encoder = new GoogleEncodedPolylineEncoder();
string encoded = encoder.Encode(coords, CancellationToken.None);

Remarks

  • 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.

Exceptions

OperationCanceledException

Thrown if the operation is canceled via cancellationToken.