Skip to content

Commit 1b87336

Browse files
CopilotCopilot
committed
Updated docs for version 0.0
1 parent 7dc6aae commit 1b87336

18 files changed

Lines changed: 2750 additions & 0 deletions

‎api-reference/0.0/PolylineAlgorithm.Abstraction.IPolylineDecoder-2.yml‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
### YamlMime:ApiPage
2+
title: Interface IPolylineDecoder<TPolyline, TValue>
3+
body:
4+
- api1: Interface IPolylineDecoder<TPolyline, TValue>
5+
id: PolylineAlgorithm_Abstraction_IPolylineDecoder_2
6+
src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs#L22
7+
metadata:
8+
uid: PolylineAlgorithm.Abstraction.IPolylineDecoder`2
9+
commentId: T:PolylineAlgorithm.Abstraction.IPolylineDecoder`2
10+
- facts:
11+
- name: Namespace
12+
value:
13+
text: PolylineAlgorithm.Abstraction
14+
url: PolylineAlgorithm.Abstraction.html
15+
- name: Assembly
16+
value: PolylineAlgorithm.dll
17+
- markdown: Defines a contract for decoding an encoded polyline into a sequence of values.
18+
- code: public interface IPolylineDecoder<TPolyline, TValue>
19+
- h4: Type Parameters
20+
- parameters:
21+
- name: TPolyline
22+
description: >-
23+
The type that represents the encoded polyline input. Common implementations use <xref href="System.String" data-throw-if-not-resolved="false"></xref>,
24+
25+
but custom wrapper types are allowed to carry additional metadata.
26+
- name: TValue
27+
description: >-
28+
The value type returned by the decoder. Typical implementations return a struct or class that
29+
30+
contains latitude and longitude (for example a <code>LatLng</code> type or a <code>ValueTuple&lt;double,double&gt;</code>).
31+
- h2: Methods
32+
- api3: Decode(TPolyline, PolylineDecodingOptions<TValue>?, CancellationToken)
33+
id: PolylineAlgorithm_Abstraction_IPolylineDecoder_2_Decode__0_PolylineAlgorithm_PolylineDecodingOptions__1__System_Threading_CancellationToken_
34+
src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs#L48
35+
metadata:
36+
uid: PolylineAlgorithm.Abstraction.IPolylineDecoder`2.Decode(`0,PolylineAlgorithm.PolylineDecodingOptions{`1},System.Threading.CancellationToken)
37+
commentId: M:PolylineAlgorithm.Abstraction.IPolylineDecoder`2.Decode(`0,PolylineAlgorithm.PolylineDecodingOptions{`1},System.Threading.CancellationToken)
38+
- markdown: >-
39+
Decodes the specified encoded polyline into an ordered sequence of values.
40+
41+
The sequence preserves the original vertex order encoded by the <code class="paramref">polyline</code>.
42+
- code: IEnumerable<TValue> Decode(TPolyline polyline, PolylineDecodingOptions<TValue>? options = null, CancellationToken cancellationToken = default)
43+
- h4: Parameters
44+
- parameters:
45+
- name: polyline
46+
type:
47+
- TPolyline
48+
description: >-
49+
The <code class="typeparamref">TPolyline</code> instance containing the encoded polyline to decode.
50+
51+
Implementations SHOULD validate the input and may throw <xref href="System.ArgumentException" data-throw-if-not-resolved="false"></xref>
52+
53+
or <xref href="System.FormatException" data-throw-if-not-resolved="false"></xref> for invalid formats.
54+
- name: options
55+
type:
56+
- text: PolylineDecodingOptions
57+
url: PolylineAlgorithm.PolylineDecodingOptions-1.html
58+
- <
59+
- TValue
60+
- '>'
61+
- '?'
62+
optional: true
63+
- name: cancellationToken
64+
type:
65+
- text: CancellationToken
66+
url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken
67+
description: >-
68+
A <xref href="System.Threading.CancellationToken" data-throw-if-not-resolved="false"></xref> to observe while decoding. If cancellation is requested,
69+
70+
implementations SHOULD stop work and throw an <xref href="System.OperationCanceledException" data-throw-if-not-resolved="false"></xref>.
71+
optional: true
72+
- h4: Returns
73+
- parameters:
74+
- type:
75+
- text: IEnumerable
76+
url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1
77+
- <
78+
- TValue
79+
- '>'
80+
description: >-
81+
An <xref href="System.Collections.Generic.IEnumerable%601" data-throw-if-not-resolved="false"></xref> of <code class="typeparamref">TValue</code> representing the decoded
82+
83+
latitude/longitude pairs (or equivalent values) in the same order they were encoded.
84+
- h4: Remarks
85+
- markdown: >-
86+
Implementations commonly follow the Google Encoded Polyline Algorithm Format, but this interface
87+
88+
does not mandate a specific encoding. Consumers should rely on a concrete decoder's documentation
89+
90+
to understand the exact encoding supported.
91+
- h4: Exceptions
92+
- parameters:
93+
- type:
94+
- text: OperationCanceledException
95+
url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception
96+
description: Thrown when the provided <code class="paramref">cancellationToken</code> requests cancellation.
97+
languageId: csharp
98+
metadata:
99+
description: Defines a contract for decoding an encoded polyline into a sequence of values.

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

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
### YamlMime:ApiPage
2+
title: Interface IPolylineEncoder<TValue, TPolyline>
3+
body:
4+
- api1: Interface IPolylineEncoder<TValue, TPolyline>
5+
id: PolylineAlgorithm_Abstraction_IPolylineEncoder_2
6+
src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs#L36
7+
metadata:
8+
uid: PolylineAlgorithm.Abstraction.IPolylineEncoder`2
9+
commentId: T:PolylineAlgorithm.Abstraction.IPolylineEncoder`2
10+
- facts:
11+
- name: Namespace
12+
value:
13+
text: PolylineAlgorithm.Abstraction
14+
url: PolylineAlgorithm.Abstraction.html
15+
- name: Assembly
16+
value: PolylineAlgorithm.dll
17+
- markdown: >-
18+
Contract for encoding a sequence of values into an encoded polyline representation.
19+
20+
Implementations interpret the generic <code class="typeparamref">TValue</code> type and produce an encoded
21+
22+
representation of those values as <code class="typeparamref">TPolyline</code>.
23+
- code: public interface IPolylineEncoder<TValue, TPolyline>
24+
- h4: Type Parameters
25+
- parameters:
26+
- name: TValue
27+
description: >-
28+
The concrete value representation used by the encoder (for example a struct or class containing
29+
30+
<code>Latitude</code> and <code>Longitude</code> values). Implementations must document the expected shape,
31+
32+
units (typically decimal degrees), and any required fields for <code class="typeparamref">TValue</code>.
33+
34+
Common shapes:
35+
36+
- 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>.
37+
38+
- A tuple-like type (for example <code>ValueTuple&lt;double,double&gt;</code>) where the encoder documents
39+
which element represents latitude and longitude.
40+
- name: TPolyline
41+
description: >-
42+
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>,
43+
44+
<code>ReadOnlyMemory&lt;char&gt;</code>, or a custom wrapper type). Concrete implementations should document
45+
46+
the chosen representation and any memory / ownership expectations.
47+
- h4: Extension Methods
48+
- list:
49+
- text: PolylineEncoderExtensions.Encode<TValue, TPolyline>(IPolylineEncoder<TValue, TPolyline>, TValue[], PolylineEncodingOptions<TValue>?, CancellationToken)
50+
url: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.html#PolylineAlgorithm_Extensions_PolylineEncoderExtensions_Encode__2_PolylineAlgorithm_Abstraction_IPolylineEncoder___0___1____0___PolylineAlgorithm_PolylineEncodingOptions___0__System_Threading_CancellationToken_
51+
- h2: Remarks
52+
- markdown: >-
53+
- This interface is intentionally minimal to allow different encoding strategies (Google encoded polyline,
54+
precision/scale variants, or custom compressed formats) to be expressed behind a common contract.
55+
- Implementations should document:
56+
- Value precision and rounding rules (for example 1e-5 for 5-decimal precision).
57+
- Value ordering and whether altitude or additional dimensions are supported.
58+
- Thread-safety guarantees: whether instances are safe to reuse concurrently or must be instantiated per-call.
59+
- Implementations are encouraged to be memory-efficient; the API accepts a <xref href="System.ReadOnlySpan%601" data-throw-if-not-resolved="false"></xref>
60+
to avoid forced allocations when callers already have contiguous memory.
61+
- h2: Methods
62+
- api3: Encode(ReadOnlySpan<TValue>, PolylineEncodingOptions<TValue>?, CancellationToken)
63+
id: PolylineAlgorithm_Abstraction_IPolylineEncoder_2_Encode_System_ReadOnlySpan__0__PolylineAlgorithm_PolylineEncodingOptions__0__System_Threading_CancellationToken_
64+
src: https://github.com/petesramek/polyline-algorithm-csharp/blob/extend-polylinealgorithm-multi-dimensional-support/src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs#L76
65+
metadata:
66+
uid: PolylineAlgorithm.Abstraction.IPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
67+
commentId: M:PolylineAlgorithm.Abstraction.IPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},PolylineAlgorithm.PolylineEncodingOptions{`0},System.Threading.CancellationToken)
68+
- markdown: >-
69+
Encodes a sequence of values into an encoded polyline representation.
70+
71+
The order of values in <code class="paramref">coordinates</code> is preserved in the encoded result.
72+
- code: TPolyline Encode(ReadOnlySpan<TValue> coordinates, PolylineEncodingOptions<TValue>? options = null, CancellationToken cancellationToken = default)
73+
- h4: Parameters
74+
- parameters:
75+
- name: coordinates
76+
type:
77+
- text: ReadOnlySpan
78+
url: https://learn.microsoft.com/dotnet/api/system.readonlyspan-1
79+
- <
80+
- TValue
81+
- '>'
82+
description: >-
83+
The collection of <code class="typeparamref">TValue</code> instances to encode into a polyline.
84+
85+
The span may be empty; implementations should return an appropriate empty encoded representation
86+
87+
(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>.
88+
- name: options
89+
type:
90+
- text: PolylineEncodingOptions
91+
url: PolylineAlgorithm.PolylineEncodingOptions-1.html
92+
- <
93+
- TValue
94+
- '>'
95+
- '?'
96+
optional: true
97+
- name: cancellationToken
98+
type:
99+
- text: CancellationToken
100+
url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken
101+
description: >-
102+
A <xref href="System.Threading.CancellationToken" data-throw-if-not-resolved="false"></xref> that can be used to cancel the encoding operation.
103+
104+
Implementations should observe this token and throw <xref href="System.OperationCanceledException" data-throw-if-not-resolved="false"></xref>
105+
106+
when cancellation is requested. For fast, in-memory encoders cancellation may be best-effort.
107+
optional: true
108+
- h4: Returns
109+
- parameters:
110+
- type:
111+
- TPolyline
112+
description: >-
113+
A <code class="typeparamref">TPolyline</code> containing the encoded polyline that represents the input values.
114+
115+
The exact format and any delimiting/terminating characters are implementation-specific and must be
116+
117+
documented by concrete encoder types.
118+
- h4: Examples
119+
- markdown: >-
120+
<pre><code class="lang-csharp">// Example pseudocode for typical usage with a string-based encoder:
121+
122+
var values = new[] {
123+
new Value { Latitude = 47.6219, Longitude = -122.3503 },
124+
new Value { Latitude = 47.6220, Longitude = -122.3504 }
125+
};
126+
127+
IPolylineEncoder&lt;Value,string&gt; encoder = new GoogleEncodedPolylineEncoder();
128+
129+
string encoded = encoder.Encode(values, CancellationToken.None);</code></pre>
130+
- h4: Remarks
131+
- markdown: >-
132+
- Implementations should validate input as appropriate and document any preconditions (for example
133+
if values must be within [-90,90] latitude and [-180,180] longitude).
134+
- For large input sequences, implementations may provide streaming or incremental encoders; those
135+
variants can still implement this interface by materializing the final encoded result.
136+
- h4: Exceptions
137+
- parameters:
138+
- type:
139+
- text: OperationCanceledException
140+
url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception
141+
description: Thrown if the operation is canceled via <code class="paramref">cancellationToken</code>.
142+
languageId: csharp
143+
metadata:
144+
description: >-
145+
Contract for encoding a sequence of values into an encoded polyline representation.
146+
147+
Implementations interpret the generic TValue type and produce an encoded
148+
149+
representation of those values as TPolyline.

0 commit comments

Comments
 (0)