diff --git a/api-reference/0.0/PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.yml b/api-reference/0.0/PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.yml new file mode 100644 index 00000000..d893f9fa --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.yml @@ -0,0 +1,233 @@ +### YamlMime:ApiPage +title: Class AbstractPolylineDecoder +body: +- api1: Class AbstractPolylineDecoder + id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2 + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L22 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2 + commentId: T:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2 +- facts: + - name: Namespace + value: + text: PolylineAlgorithm.Abstraction + url: PolylineAlgorithm.Abstraction.html + - name: Assembly + value: PolylineAlgorithm.dll +- markdown: Provides a base implementation for decoding encoded polyline strings into sequences of geographic coordinates. +- code: 'public abstract class AbstractPolylineDecoder : IPolylineDecoder' +- h4: Type Parameters +- parameters: + - name: TPolyline + description: The type that represents the encoded polyline input. + - name: TCoordinate + description: The type that represents a decoded geographic coordinate. +- h4: Inheritance +- inheritance: + - text: object + url: https://learn.microsoft.com/dotnet/api/system.object + - text: AbstractPolylineDecoder + url: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.html +- h4: Implements +- list: + - text: IPolylineDecoder + url: PolylineAlgorithm.Abstraction.IPolylineDecoder-2.html +- h4: Inherited Members +- list: + - text: object.Equals(object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object) + - text: object.Equals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object) + - text: object.GetHashCode() + url: https://learn.microsoft.com/dotnet/api/system.object.gethashcode + - text: object.GetType() + url: https://learn.microsoft.com/dotnet/api/system.object.gettype + - text: object.MemberwiseClone() + url: https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone + - text: object.ReferenceEquals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.referenceequals + - text: object.ToString() + url: https://learn.microsoft.com/dotnet/api/system.object.tostring +- h2: Remarks +- markdown: >- + Derive from this class to implement a decoder for a specific polyline type. Override + + and to provide type-specific behavior. +- h2: Constructors +- api3: AbstractPolylineDecoder() + id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2__ctor + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L28 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.#ctor + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.#ctor +- markdown: Initializes a new instance of the class with default encoding options. +- code: protected AbstractPolylineDecoder() +- api3: AbstractPolylineDecoder(PolylineEncodingOptions) + id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2__ctor_PolylineAlgorithm_PolylineEncodingOptions_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L40 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.#ctor(PolylineAlgorithm.PolylineEncodingOptions) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.#ctor(PolylineAlgorithm.PolylineEncodingOptions) +- markdown: Initializes a new instance of the class with the specified encoding options. +- code: protected AbstractPolylineDecoder(PolylineEncodingOptions options) +- h4: Parameters +- parameters: + - name: options + type: + - text: PolylineEncodingOptions + url: PolylineAlgorithm.PolylineEncodingOptions.html + description: The to use for encoding operations. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentNullException + url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception + description: Thrown when options is null. +- h2: Properties +- api3: Options + id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_Options + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L54 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Options + commentId: P:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Options +- markdown: Gets the encoding options used by this polyline decoder. +- code: public PolylineEncodingOptions Options { get; } +- h4: Property Value +- parameters: + - type: + - text: PolylineEncodingOptions + url: PolylineAlgorithm.PolylineEncodingOptions.html +- h2: Methods +- api3: CreateCoordinate(double, double) + id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_CreateCoordinate_System_Double_System_Double_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L202 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.CreateCoordinate(System.Double,System.Double) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.CreateCoordinate(System.Double,System.Double) +- markdown: Creates a TCoordinate instance from the specified latitude and longitude values. +- code: protected abstract TCoordinate CreateCoordinate(double latitude, double longitude) +- h4: Parameters +- parameters: + - name: latitude + type: + - text: double + url: https://learn.microsoft.com/dotnet/api/system.double + description: The latitude component of the coordinate, in degrees. + - name: longitude + type: + - text: double + url: https://learn.microsoft.com/dotnet/api/system.double + description: The longitude component of the coordinate, in degrees. +- h4: Returns +- parameters: + - type: + - TCoordinate + description: A TCoordinate instance representing the specified geographic coordinate. +- api3: Decode(TPolyline, CancellationToken) + id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_Decode__0_System_Threading_CancellationToken_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L81 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Decode(`0,System.Threading.CancellationToken) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Decode(`0,System.Threading.CancellationToken) +- markdown: >- + Decodes an encoded TPolyline into a sequence of TCoordinate instances, + + with support for cancellation. +- code: public IEnumerable Decode(TPolyline polyline, CancellationToken cancellationToken = default) +- h4: Parameters +- parameters: + - name: polyline + type: + - TPolyline + description: The TPolyline instance containing the encoded polyline string to decode. + - name: cancellationToken + type: + - text: CancellationToken + url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken + description: A that can be used to cancel the decoding operation. + optional: true +- h4: Returns +- parameters: + - type: + - text: IEnumerable + url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1 + - < + - TCoordinate + - '>' + description: An of TCoordinate representing the decoded latitude and longitude pairs. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentNullException + url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception + description: Thrown when polyline is null. + - type: + - text: ArgumentException + url: https://learn.microsoft.com/dotnet/api/system.argumentexception + description: Thrown when polyline is empty. + - type: + - text: InvalidPolylineException + url: PolylineAlgorithm.InvalidPolylineException.html + description: Thrown when the polyline format is invalid or malformed at a specific position. + - type: + - text: OperationCanceledException + url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception + description: Thrown when cancellationToken is canceled during decoding. +- api3: GetReadOnlyMemory(in TPolyline) + id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_GetReadOnlyMemory__0__ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L187 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.GetReadOnlyMemory(`0@) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.GetReadOnlyMemory(`0@) +- markdown: Extracts the underlying read-only memory region of characters from the specified polyline instance. +- code: protected abstract ReadOnlyMemory GetReadOnlyMemory(in TPolyline polyline) +- h4: Parameters +- parameters: + - name: polyline + type: + - TPolyline + description: The TPolyline instance from which to extract the character sequence. +- h4: Returns +- parameters: + - type: + - text: ReadOnlyMemory + url: https://learn.microsoft.com/dotnet/api/system.readonlymemory-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + description: A of representing the encoded polyline characters. +- api3: ValidateFormat(ReadOnlyMemory, ILogger?) + id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_ValidateFormat_System_ReadOnlyMemory_System_Char__Microsoft_Extensions_Logging_ILogger_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L167 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.ValidateFormat(System.ReadOnlyMemory{System.Char},Microsoft.Extensions.Logging.ILogger) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.ValidateFormat(System.ReadOnlyMemory{System.Char},Microsoft.Extensions.Logging.ILogger) +- markdown: Validates the format of the polyline character sequence, ensuring all characters are within the allowed range. +- code: protected virtual void ValidateFormat(ReadOnlyMemory sequence, ILogger? logger) +- h4: Parameters +- parameters: + - name: sequence + type: + - text: ReadOnlyMemory + url: https://learn.microsoft.com/dotnet/api/system.readonlymemory-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + description: The read-only memory region of characters representing the polyline to validate. + - name: logger + type: + - text: ILogger + url: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger + - '?' + description: An optional used to log a warning when format validation fails. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentException + url: https://learn.microsoft.com/dotnet/api/system.argumentexception + description: Thrown when the polyline contains characters outside the valid encoding range or has an invalid block structure. +languageId: csharp +metadata: + description: Provides a base implementation for decoding encoded polyline strings into sequences of geographic coordinates. diff --git a/api-reference/0.0/PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.yml b/api-reference/0.0/PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.yml new file mode 100644 index 00000000..f93c2e50 --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.yml @@ -0,0 +1,219 @@ +### YamlMime:ApiPage +title: Class AbstractPolylineEncoder +body: +- api1: Class AbstractPolylineEncoder + id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2 + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L27 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2 + commentId: T:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2 +- facts: + - name: Namespace + value: + text: PolylineAlgorithm.Abstraction + url: PolylineAlgorithm.Abstraction.html + - name: Assembly + value: PolylineAlgorithm.dll +- markdown: Provides a base implementation for encoding sequences of geographic coordinates into encoded polyline strings. +- code: 'public abstract class AbstractPolylineEncoder : IPolylineEncoder' +- h4: Type Parameters +- parameters: + - name: TCoordinate + description: The type that represents a geographic coordinate to encode. + - name: TPolyline + description: The type that represents the encoded polyline output. +- h4: Inheritance +- inheritance: + - text: object + url: https://learn.microsoft.com/dotnet/api/system.object + - text: AbstractPolylineEncoder + url: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.html +- h4: Implements +- list: + - text: IPolylineEncoder + url: PolylineAlgorithm.Abstraction.IPolylineEncoder-2.html +- h4: Inherited Members +- list: + - text: object.Equals(object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object) + - text: object.Equals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object) + - text: object.GetHashCode() + url: https://learn.microsoft.com/dotnet/api/system.object.gethashcode + - text: object.GetType() + url: https://learn.microsoft.com/dotnet/api/system.object.gettype + - text: object.MemberwiseClone() + url: https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone + - text: object.ReferenceEquals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.referenceequals + - text: object.ToString() + url: https://learn.microsoft.com/dotnet/api/system.object.tostring +- h4: Extension Methods +- list: + - text: PolylineEncoderExtensions.Encode(IPolylineEncoder, List) + url: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.html#PolylineAlgorithm_Extensions_PolylineEncoderExtensions_Encode__2_PolylineAlgorithm_Abstraction_IPolylineEncoder___0___1__System_Collections_Generic_List___0__ + - text: PolylineEncoderExtensions.Encode(IPolylineEncoder, TCoordinate[]) + url: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.html#PolylineAlgorithm_Extensions_PolylineEncoderExtensions_Encode__2_PolylineAlgorithm_Abstraction_IPolylineEncoder___0___1____0___ +- h2: Remarks +- markdown: >- + Derive from this class to implement an encoder for a specific coordinate and polyline type. Override + + , , and to provide type-specific behavior. +- h2: Constructors +- api3: AbstractPolylineEncoder() + id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2__ctor + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L33 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.#ctor + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.#ctor +- markdown: Initializes a new instance of the class with default encoding options. +- code: protected AbstractPolylineEncoder() +- api3: AbstractPolylineEncoder(PolylineEncodingOptions) + id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2__ctor_PolylineAlgorithm_PolylineEncodingOptions_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L43 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.#ctor(PolylineAlgorithm.PolylineEncodingOptions) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.#ctor(PolylineAlgorithm.PolylineEncodingOptions) +- markdown: Initializes a new instance of the class with the specified encoding options. +- code: protected AbstractPolylineEncoder(PolylineEncodingOptions options) +- h4: Parameters +- parameters: + - name: options + type: + - text: PolylineEncodingOptions + url: PolylineAlgorithm.PolylineEncodingOptions.html + description: The to use for encoding operations. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentNullException + url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception + description: Thrown when options is null +- h2: Properties +- api3: Options + id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_Options + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L57 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.Options + commentId: P:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.Options +- markdown: Gets the encoding options used by this polyline encoder. +- code: public PolylineEncodingOptions Options { get; } +- h4: Property Value +- parameters: + - type: + - text: PolylineEncodingOptions + url: PolylineAlgorithm.PolylineEncodingOptions.html +- h2: Methods +- api3: CreatePolyline(ReadOnlyMemory) + id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_CreatePolyline_System_ReadOnlyMemory_System_Char__ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L174 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.CreatePolyline(System.ReadOnlyMemory{System.Char}) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.CreatePolyline(System.ReadOnlyMemory{System.Char}) +- markdown: Creates a polyline instance from the provided read-only sequence of characters. +- code: protected abstract TPolyline CreatePolyline(ReadOnlyMemory polyline) +- h4: Parameters +- parameters: + - name: polyline + type: + - text: ReadOnlyMemory + url: https://learn.microsoft.com/dotnet/api/system.readonlymemory-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + description: A containing the encoded polyline characters. +- h4: Returns +- parameters: + - type: + - TPolyline + description: An instance of TPolyline representing the encoded polyline. +- api3: Encode(ReadOnlySpan, CancellationToken) + id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_Encode_System_ReadOnlySpan__0__System_Threading_CancellationToken_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L80 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},System.Threading.CancellationToken) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},System.Threading.CancellationToken) +- markdown: Encodes a collection of TCoordinate instances into an encoded TPolyline string. +- code: >- + [SuppressMessage("Design", "MA0051:Method is too long", Justification = "Method contains local methods. Actual method only 55 lines.")] + + public TPolyline Encode(ReadOnlySpan coordinates, CancellationToken cancellationToken = default) +- h4: Parameters +- parameters: + - name: coordinates + type: + - text: ReadOnlySpan + url: https://learn.microsoft.com/dotnet/api/system.readonlyspan-1 + - < + - TCoordinate + - '>' + description: The collection of TCoordinate objects to encode. + - name: cancellationToken + type: + - text: CancellationToken + url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken + description: A that can be used to cancel the encoding operation. + optional: true +- h4: Returns +- parameters: + - type: + - TPolyline + description: An instance of TPolyline representing the encoded coordinates. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentNullException + url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception + description: Thrown when coordinates is null. + - type: + - text: ArgumentException + url: https://learn.microsoft.com/dotnet/api/system.argumentexception + description: Thrown when coordinates is an empty enumeration. + - type: + - text: InvalidOperationException + url: https://learn.microsoft.com/dotnet/api/system.invalidoperationexception + description: Thrown when the internal encoding buffer cannot accommodate the encoded value. +- api3: GetLatitude(TCoordinate) + id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_GetLatitude__0_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L194 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.GetLatitude(`0) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.GetLatitude(`0) +- markdown: Extracts the latitude value from the specified coordinate. +- code: protected abstract double GetLatitude(TCoordinate current) +- h4: Parameters +- parameters: + - name: current + type: + - TCoordinate + description: The coordinate from which to extract the latitude. +- h4: Returns +- parameters: + - type: + - text: double + url: https://learn.microsoft.com/dotnet/api/system.double + description: The latitude value as a . +- api3: GetLongitude(TCoordinate) + id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_GetLongitude__0_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L184 + metadata: + uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.GetLongitude(`0) + commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.GetLongitude(`0) +- markdown: Extracts the longitude value from the specified coordinate. +- code: protected abstract double GetLongitude(TCoordinate current) +- h4: Parameters +- parameters: + - name: current + type: + - TCoordinate + description: The coordinate from which to extract the longitude. +- h4: Returns +- parameters: + - type: + - text: double + url: https://learn.microsoft.com/dotnet/api/system.double + description: The longitude value as a . +languageId: csharp +metadata: + description: Provides a base implementation for encoding sequences of geographic coordinates into encoded polyline strings. diff --git a/api-reference/0.0/PolylineAlgorithm.Abstraction.IPolylineDecoder-2.yml b/api-reference/0.0/PolylineAlgorithm.Abstraction.IPolylineDecoder-2.yml new file mode 100644 index 00000000..91d1eba4 --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.Abstraction.IPolylineDecoder-2.yml @@ -0,0 +1,90 @@ +### YamlMime:ApiPage +title: Interface IPolylineDecoder +body: +- api1: Interface IPolylineDecoder + id: PolylineAlgorithm_Abstraction_IPolylineDecoder_2 + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs#L22 + metadata: + uid: PolylineAlgorithm.Abstraction.IPolylineDecoder`2 + commentId: T:PolylineAlgorithm.Abstraction.IPolylineDecoder`2 +- facts: + - name: Namespace + value: + text: PolylineAlgorithm.Abstraction + url: PolylineAlgorithm.Abstraction.html + - name: Assembly + value: PolylineAlgorithm.dll +- markdown: Defines a contract for decoding an encoded polyline into a sequence of geographic coordinates. +- code: public interface IPolylineDecoder +- h4: Type Parameters +- parameters: + - name: TPolyline + description: >- + The type that represents the encoded polyline input. Common implementations use , + + but custom wrapper types are allowed to carry additional metadata. + - name: TValue + description: >- + The coordinate type returned by the decoder. Typical implementations return a struct or class that + + contains latitude and longitude (for example a LatLng type or a ValueTuple<double,double>). +- h2: Methods +- api3: Decode(TPolyline, CancellationToken) + id: PolylineAlgorithm_Abstraction_IPolylineDecoder_2_Decode__0_System_Threading_CancellationToken_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs#L48 + metadata: + uid: PolylineAlgorithm.Abstraction.IPolylineDecoder`2.Decode(`0,System.Threading.CancellationToken) + commentId: M:PolylineAlgorithm.Abstraction.IPolylineDecoder`2.Decode(`0,System.Threading.CancellationToken) +- markdown: >- + Decodes the specified encoded polyline into an ordered sequence of geographic coordinates. + + The sequence preserves the original vertex order encoded by the polyline. +- code: IEnumerable Decode(TPolyline polyline, CancellationToken cancellationToken = default) +- h4: Parameters +- parameters: + - name: polyline + type: + - TPolyline + description: >- + The TPolyline instance containing the encoded polyline to decode. + + Implementations SHOULD validate the input and may throw + + or for invalid formats. + - name: cancellationToken + type: + - text: CancellationToken + url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken + description: >- + A to observe while decoding. If cancellation is requested, + + implementations SHOULD stop work and throw an . + optional: true +- h4: Returns +- parameters: + - type: + - text: IEnumerable + url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1 + - < + - TValue + - '>' + description: >- + An of TValue representing the decoded + + latitude/longitude pairs (or equivalent coordinates) in the same order they were encoded. +- h4: Remarks +- markdown: >- + Implementations commonly follow the Google Encoded Polyline Algorithm Format, but this interface + + does not mandate a specific encoding. Consumers should rely on a concrete decoder's documentation + + to understand the exact encoding supported. +- h4: Exceptions +- parameters: + - type: + - text: OperationCanceledException + url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception + description: Thrown when the provided cancellationToken requests cancellation. +languageId: csharp +metadata: + description: Defines a contract for decoding an encoded polyline into a sequence of geographic coordinates. diff --git a/api-reference/0.0/PolylineAlgorithm.Abstraction.IPolylineEncoder-2.yml b/api-reference/0.0/PolylineAlgorithm.Abstraction.IPolylineEncoder-2.yml new file mode 100644 index 00000000..7af64eaa --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.Abstraction.IPolylineEncoder-2.yml @@ -0,0 +1,142 @@ +### YamlMime:ApiPage +title: Interface IPolylineEncoder +body: +- api1: Interface IPolylineEncoder + id: PolylineAlgorithm_Abstraction_IPolylineEncoder_2 + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/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 TValue type and produce an encoded + + representation of those coordinates as TPolyline. +- code: public interface IPolylineEncoder +- h4: Type Parameters +- parameters: + - name: TValue + description: >- + 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. + - name: TPolyline + description: >- + 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. +- h4: Extension Methods +- list: + - text: PolylineEncoderExtensions.Encode(IPolylineEncoder, List) + url: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.html#PolylineAlgorithm_Extensions_PolylineEncoderExtensions_Encode__2_PolylineAlgorithm_Abstraction_IPolylineEncoder___0___1__System_Collections_Generic_List___0__ + - text: PolylineEncoderExtensions.Encode(IPolylineEncoder, 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 + to avoid forced allocations when callers already have contiguous memory. +- h2: Methods +- api3: Encode(ReadOnlySpan, CancellationToken) + id: PolylineAlgorithm_Abstraction_IPolylineEncoder_2_Encode_System_ReadOnlySpan__0__System_Threading_CancellationToken_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/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 coordinates is preserved in the encoded result. +- code: TPolyline Encode(ReadOnlySpan 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 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. + - name: cancellationToken + type: + - text: CancellationToken + url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken + description: >- + A that can be used to cancel the encoding operation. + + Implementations should observe this token and throw + + when cancellation is requested. For fast, in-memory encoders cancellation may be best-effort. + optional: true +- h4: Returns +- parameters: + - type: + - TPolyline + description: >- + 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. +- h4: Examples +- markdown: >- + 
// 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);
+- 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 cancellationToken. +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. diff --git a/api-reference/0.0/PolylineAlgorithm.Abstraction.yml b/api-reference/0.0/PolylineAlgorithm.Abstraction.yml new file mode 100644 index 00000000..e9de48f7 --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.Abstraction.yml @@ -0,0 +1,34 @@ +### YamlMime:ApiPage +title: Namespace PolylineAlgorithm.Abstraction +body: +- api1: Namespace PolylineAlgorithm.Abstraction + id: PolylineAlgorithm_Abstraction + metadata: + uid: PolylineAlgorithm.Abstraction + commentId: N:PolylineAlgorithm.Abstraction +- h3: Classes +- parameters: + - type: + text: AbstractPolylineDecoder + url: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.html + description: Provides a base implementation for decoding encoded polyline strings into sequences of geographic coordinates. + - type: + text: AbstractPolylineEncoder + url: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.html + description: Provides a base implementation for encoding sequences of geographic coordinates into encoded polyline strings. +- h3: Interfaces +- parameters: + - type: + text: IPolylineDecoder + url: PolylineAlgorithm.Abstraction.IPolylineDecoder-2.html + description: Defines a contract for decoding an encoded polyline into a sequence of geographic coordinates. + - type: + text: IPolylineEncoder + url: PolylineAlgorithm.Abstraction.IPolylineEncoder-2.html + 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. +languageId: csharp diff --git a/api-reference/0.0/PolylineAlgorithm.Extensions.PolylineDecoderExtensions.yml b/api-reference/0.0/PolylineAlgorithm.Extensions.PolylineDecoderExtensions.yml new file mode 100644 index 00000000..c6d907de --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.Extensions.PolylineDecoderExtensions.yml @@ -0,0 +1,195 @@ +### YamlMime:ApiPage +title: Class PolylineDecoderExtensions +body: +- api1: Class PolylineDecoderExtensions + id: PolylineAlgorithm_Extensions_PolylineDecoderExtensions + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Extensions/PolylineDecoderExtensions.cs#L16 + metadata: + uid: PolylineAlgorithm.Extensions.PolylineDecoderExtensions + commentId: T:PolylineAlgorithm.Extensions.PolylineDecoderExtensions +- facts: + - name: Namespace + value: + text: PolylineAlgorithm.Extensions + url: PolylineAlgorithm.Extensions.html + - name: Assembly + value: PolylineAlgorithm.dll +- markdown: Provides extension methods for the interface to facilitate decoding encoded polylines. +- code: public static class PolylineDecoderExtensions +- h4: Inheritance +- inheritance: + - text: object + url: https://learn.microsoft.com/dotnet/api/system.object + - text: PolylineDecoderExtensions + url: PolylineAlgorithm.Extensions.PolylineDecoderExtensions.html +- h4: Inherited Members +- list: + - text: object.Equals(object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object) + - text: object.Equals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object) + - text: object.GetHashCode() + url: https://learn.microsoft.com/dotnet/api/system.object.gethashcode + - text: object.GetType() + url: https://learn.microsoft.com/dotnet/api/system.object.gettype + - text: object.MemberwiseClone() + url: https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone + - text: object.ReferenceEquals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.referenceequals + - text: object.ToString() + url: https://learn.microsoft.com/dotnet/api/system.object.tostring +- h2: Methods +- api3: Decode(IPolylineDecoder, char[]) + id: PolylineAlgorithm_Extensions_PolylineDecoderExtensions_Decode__1_PolylineAlgorithm_Abstraction_IPolylineDecoder_System_String___0__System_Char___ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Extensions/PolylineDecoderExtensions.cs#L33 + metadata: + uid: PolylineAlgorithm.Extensions.PolylineDecoderExtensions.Decode``1(PolylineAlgorithm.Abstraction.IPolylineDecoder{System.String,``0},System.Char[]) + commentId: M:PolylineAlgorithm.Extensions.PolylineDecoderExtensions.Decode``1(PolylineAlgorithm.Abstraction.IPolylineDecoder{System.String,``0},System.Char[]) +- markdown: Decodes an encoded polyline represented as a character array into a sequence of geographic coordinates. +- code: public static IEnumerable Decode(this IPolylineDecoder decoder, char[] polyline) +- h4: Parameters +- parameters: + - name: decoder + type: + - text: IPolylineDecoder + url: PolylineAlgorithm.Abstraction.IPolylineDecoder-2.html + - < + - text: string + url: https://learn.microsoft.com/dotnet/api/system.string + - ',' + - " " + - TValue + - '>' + description: The instance used to perform the decoding operation. + - name: polyline + type: + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '[' + - ']' + description: The encoded polyline as a character array to decode. The array is converted to a string internally. +- h4: Returns +- parameters: + - type: + - text: IEnumerable + url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1 + - < + - TValue + - '>' + description: An of TValue containing the decoded coordinate pairs. +- h4: Type Parameters +- parameters: + - name: TValue + description: The coordinate type returned by the decoder. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentNullException + url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception + description: Thrown when decoder or polyline is null. +- api3: Decode(IPolylineDecoder, ReadOnlyMemory) + id: PolylineAlgorithm_Extensions_PolylineDecoderExtensions_Decode__1_PolylineAlgorithm_Abstraction_IPolylineDecoder_System_String___0__System_ReadOnlyMemory_System_Char__ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Extensions/PolylineDecoderExtensions.cs#L61 + metadata: + uid: PolylineAlgorithm.Extensions.PolylineDecoderExtensions.Decode``1(PolylineAlgorithm.Abstraction.IPolylineDecoder{System.String,``0},System.ReadOnlyMemory{System.Char}) + commentId: M:PolylineAlgorithm.Extensions.PolylineDecoderExtensions.Decode``1(PolylineAlgorithm.Abstraction.IPolylineDecoder{System.String,``0},System.ReadOnlyMemory{System.Char}) +- markdown: Decodes an encoded polyline represented as a read-only memory of characters into a sequence of geographic coordinates. +- code: public static IEnumerable Decode(this IPolylineDecoder decoder, ReadOnlyMemory polyline) +- h4: Parameters +- parameters: + - name: decoder + type: + - text: IPolylineDecoder + url: PolylineAlgorithm.Abstraction.IPolylineDecoder-2.html + - < + - text: string + url: https://learn.microsoft.com/dotnet/api/system.string + - ',' + - " " + - TValue + - '>' + description: The instance used to perform the decoding operation. + - name: polyline + type: + - text: ReadOnlyMemory + url: https://learn.microsoft.com/dotnet/api/system.readonlymemory-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + description: The encoded polyline as a read-only memory of characters to decode. The memory is converted to a string internally. +- h4: Returns +- parameters: + - type: + - text: IEnumerable + url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1 + - < + - TValue + - '>' + description: An of TValue containing the decoded coordinate pairs. +- h4: Type Parameters +- parameters: + - name: TValue + description: The coordinate type returned by the decoder. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentNullException + url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception + description: Thrown when decoder is null. +- api3: Decode(IPolylineDecoder, TValue>, string) + id: PolylineAlgorithm_Extensions_PolylineDecoderExtensions_Decode__1_PolylineAlgorithm_Abstraction_IPolylineDecoder_System_ReadOnlyMemory_System_Char____0__System_String_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Extensions/PolylineDecoderExtensions.cs#L86 + metadata: + uid: PolylineAlgorithm.Extensions.PolylineDecoderExtensions.Decode``1(PolylineAlgorithm.Abstraction.IPolylineDecoder{System.ReadOnlyMemory{System.Char},``0},System.String) + commentId: M:PolylineAlgorithm.Extensions.PolylineDecoderExtensions.Decode``1(PolylineAlgorithm.Abstraction.IPolylineDecoder{System.ReadOnlyMemory{System.Char},``0},System.String) +- markdown: >- + Decodes an encoded polyline string into a sequence of geographic coordinates, + + using a decoder that accepts of . +- code: public static IEnumerable Decode(this IPolylineDecoder, TValue> decoder, string polyline) +- h4: Parameters +- parameters: + - name: decoder + type: + - text: IPolylineDecoder + url: PolylineAlgorithm.Abstraction.IPolylineDecoder-2.html + - < + - text: ReadOnlyMemory + url: https://learn.microsoft.com/dotnet/api/system.readonlymemory-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + - ',' + - " " + - TValue + - '>' + description: The instance used to perform the decoding operation. + - name: polyline + type: + - text: string + url: https://learn.microsoft.com/dotnet/api/system.string + description: The encoded polyline string to decode. The string is converted to internally. +- h4: Returns +- parameters: + - type: + - text: IEnumerable + url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1 + - < + - TValue + - '>' + description: An of TValue containing the decoded coordinate pairs. +- h4: Type Parameters +- parameters: + - name: TValue + description: The coordinate type returned by the decoder. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentNullException + url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception + description: Thrown when decoder or polyline is null. +languageId: csharp +metadata: + description: Provides extension methods for the interface to facilitate decoding encoded polylines. diff --git a/api-reference/0.0/PolylineAlgorithm.Extensions.PolylineEncoderExtensions.yml b/api-reference/0.0/PolylineAlgorithm.Extensions.PolylineEncoderExtensions.yml new file mode 100644 index 00000000..93a5bd77 --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.Extensions.PolylineEncoderExtensions.yml @@ -0,0 +1,139 @@ +### YamlMime:ApiPage +title: Class PolylineEncoderExtensions +body: +- api1: Class PolylineEncoderExtensions + id: PolylineAlgorithm_Extensions_PolylineEncoderExtensions + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs#L19 + metadata: + uid: PolylineAlgorithm.Extensions.PolylineEncoderExtensions + commentId: T:PolylineAlgorithm.Extensions.PolylineEncoderExtensions +- facts: + - name: Namespace + value: + text: PolylineAlgorithm.Extensions + url: PolylineAlgorithm.Extensions.html + - name: Assembly + value: PolylineAlgorithm.dll +- markdown: Provides extension methods for the interface to facilitate encoding geographic coordinates into polylines. +- code: public static class PolylineEncoderExtensions +- h4: Inheritance +- inheritance: + - text: object + url: https://learn.microsoft.com/dotnet/api/system.object + - text: PolylineEncoderExtensions + url: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.html +- h4: Inherited Members +- list: + - text: object.Equals(object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object) + - text: object.Equals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object) + - text: object.GetHashCode() + url: https://learn.microsoft.com/dotnet/api/system.object.gethashcode + - text: object.GetType() + url: https://learn.microsoft.com/dotnet/api/system.object.gettype + - text: object.MemberwiseClone() + url: https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone + - text: object.ReferenceEquals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.referenceequals + - text: object.ToString() + url: https://learn.microsoft.com/dotnet/api/system.object.tostring +- h2: Methods +- api3: Encode(IPolylineEncoder, List) + id: PolylineAlgorithm_Extensions_PolylineEncoderExtensions_Encode__2_PolylineAlgorithm_Abstraction_IPolylineEncoder___0___1__System_Collections_Generic_List___0__ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs#L37 + metadata: + uid: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.Encode``2(PolylineAlgorithm.Abstraction.IPolylineEncoder{``0,``1},System.Collections.Generic.List{``0}) + commentId: M:PolylineAlgorithm.Extensions.PolylineEncoderExtensions.Encode``2(PolylineAlgorithm.Abstraction.IPolylineEncoder{``0,``1},System.Collections.Generic.List{``0}) +- markdown: Encodes a of TCoordinate instances into an encoded polyline. +- code: >- + [SuppressMessage("Design", "CA1002:Do not expose generic lists", Justification = "We need a list as we do need to marshal it as span.")] + + [SuppressMessage("Design", "MA0016:Prefer using collection abstraction instead of implementation", Justification = "We need a list as we do need to marshal it as span.")] + + public static TPolyline Encode(this IPolylineEncoder encoder, List coordinates) +- h4: Parameters +- parameters: + - name: encoder + type: + - text: IPolylineEncoder + url: PolylineAlgorithm.Abstraction.IPolylineEncoder-2.html + - < + - TCoordinate + - ',' + - " " + - TPolyline + - '>' + description: The instance used to perform the encoding operation. + - name: coordinates + type: + - text: List + url: https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1 + - < + - TCoordinate + - '>' + description: The list of TCoordinate objects to encode. +- h4: Returns +- parameters: + - type: + - TPolyline + description: A TPolyline instance representing the encoded polyline for the provided coordinates. +- h4: Type Parameters +- parameters: + - name: TCoordinate + description: The type that represents a geographic coordinate to encode. + - name: TPolyline + description: The type that represents the encoded polyline output. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentNullException + url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception + description: Thrown when encoder or coordinates is null. +- api3: Encode(IPolylineEncoder, TCoordinate[]) + id: PolylineAlgorithm_Extensions_PolylineEncoderExtensions_Encode__2_PolylineAlgorithm_Abstraction_IPolylineEncoder___0___1____0___ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs#L73 + metadata: + uid: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.Encode``2(PolylineAlgorithm.Abstraction.IPolylineEncoder{``0,``1},``0[]) + commentId: M:PolylineAlgorithm.Extensions.PolylineEncoderExtensions.Encode``2(PolylineAlgorithm.Abstraction.IPolylineEncoder{``0,``1},``0[]) +- markdown: Encodes an array of TCoordinate instances into an encoded polyline. +- code: public static TPolyline Encode(this IPolylineEncoder encoder, TCoordinate[] coordinates) +- h4: Parameters +- parameters: + - name: encoder + type: + - text: IPolylineEncoder + url: PolylineAlgorithm.Abstraction.IPolylineEncoder-2.html + - < + - TCoordinate + - ',' + - " " + - TPolyline + - '>' + description: The instance used to perform the encoding operation. + - name: coordinates + type: + - TCoordinate + - '[' + - ']' + description: The array of TCoordinate objects to encode. +- h4: Returns +- parameters: + - type: + - TPolyline + description: A TPolyline instance representing the encoded polyline for the provided coordinates. +- h4: Type Parameters +- parameters: + - name: TCoordinate + description: The type that represents a geographic coordinate to encode. + - name: TPolyline + description: The type that represents the encoded polyline output. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentNullException + url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception + description: Thrown when encoder or coordinates is null. +languageId: csharp +metadata: + description: Provides extension methods for the interface to facilitate encoding geographic coordinates into polylines. diff --git a/api-reference/0.0/PolylineAlgorithm.Extensions.yml b/api-reference/0.0/PolylineAlgorithm.Extensions.yml new file mode 100644 index 00000000..c39da0ca --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.Extensions.yml @@ -0,0 +1,19 @@ +### YamlMime:ApiPage +title: Namespace PolylineAlgorithm.Extensions +body: +- api1: Namespace PolylineAlgorithm.Extensions + id: PolylineAlgorithm_Extensions + metadata: + uid: PolylineAlgorithm.Extensions + commentId: N:PolylineAlgorithm.Extensions +- h3: Classes +- parameters: + - type: + text: PolylineDecoderExtensions + url: PolylineAlgorithm.Extensions.PolylineDecoderExtensions.html + description: Provides extension methods for the interface to facilitate decoding encoded polylines. + - type: + text: PolylineEncoderExtensions + url: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.html + description: Provides extension methods for the interface to facilitate encoding geographic coordinates into polylines. +languageId: csharp diff --git a/api-reference/0.0/PolylineAlgorithm.InvalidPolylineException.yml b/api-reference/0.0/PolylineAlgorithm.InvalidPolylineException.yml new file mode 100644 index 00000000..8d2a2345 --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.InvalidPolylineException.yml @@ -0,0 +1,102 @@ +### YamlMime:ApiPage +title: Class InvalidPolylineException +body: +- api1: Class InvalidPolylineException + id: PolylineAlgorithm_InvalidPolylineException + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/InvalidPolylineException.cs#L17 + metadata: + uid: PolylineAlgorithm.InvalidPolylineException + commentId: T:PolylineAlgorithm.InvalidPolylineException +- facts: + - name: Namespace + value: + text: PolylineAlgorithm + url: PolylineAlgorithm.html + - name: Assembly + value: PolylineAlgorithm.dll +- markdown: Exception thrown when a polyline is determined to be malformed or invalid during processing. +- code: 'public sealed class InvalidPolylineException : Exception, ISerializable' +- h4: Inheritance +- inheritance: + - text: object + url: https://learn.microsoft.com/dotnet/api/system.object + - text: Exception + url: https://learn.microsoft.com/dotnet/api/system.exception + - text: InvalidPolylineException + url: PolylineAlgorithm.InvalidPolylineException.html +- h4: Implements +- list: + - text: ISerializable + url: https://learn.microsoft.com/dotnet/api/system.runtime.serialization.iserializable +- h4: Inherited Members +- list: + - text: Exception.GetBaseException() + url: https://learn.microsoft.com/dotnet/api/system.exception.getbaseexception + - text: Exception.GetObjectData(SerializationInfo, StreamingContext) + url: https://learn.microsoft.com/dotnet/api/system.exception.getobjectdata + - text: Exception.GetType() + url: https://learn.microsoft.com/dotnet/api/system.exception.gettype + - text: Exception.ToString() + url: https://learn.microsoft.com/dotnet/api/system.exception.tostring + - text: Exception.Data + url: https://learn.microsoft.com/dotnet/api/system.exception.data + - text: Exception.HelpLink + url: https://learn.microsoft.com/dotnet/api/system.exception.helplink + - text: Exception.HResult + url: https://learn.microsoft.com/dotnet/api/system.exception.hresult + - text: Exception.InnerException + url: https://learn.microsoft.com/dotnet/api/system.exception.innerexception + - text: Exception.Message + url: https://learn.microsoft.com/dotnet/api/system.exception.message + - text: Exception.Source + url: https://learn.microsoft.com/dotnet/api/system.exception.source + - text: Exception.StackTrace + url: https://learn.microsoft.com/dotnet/api/system.exception.stacktrace + - text: Exception.TargetSite + url: https://learn.microsoft.com/dotnet/api/system.exception.targetsite + - text: object.Equals(object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object) + - text: object.Equals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object) + - text: object.GetHashCode() + url: https://learn.microsoft.com/dotnet/api/system.object.gethashcode + - text: object.GetType() + url: https://learn.microsoft.com/dotnet/api/system.object.gettype + - text: object.ReferenceEquals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.referenceequals + - text: object.ToString() + url: https://learn.microsoft.com/dotnet/api/system.object.tostring +- h2: Remarks +- markdown: This exception is used internally to indicate that a polyline string does not conform to the expected format or contains errors. +- h2: Constructors +- api3: InvalidPolylineException() + id: PolylineAlgorithm_InvalidPolylineException__ctor + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/InvalidPolylineException.cs#L22 + metadata: + uid: PolylineAlgorithm.InvalidPolylineException.#ctor + commentId: M:PolylineAlgorithm.InvalidPolylineException.#ctor +- markdown: Initializes a new instance of the class. +- code: public InvalidPolylineException() +- api3: InvalidPolylineException(string, Exception) + id: PolylineAlgorithm_InvalidPolylineException__ctor_System_String_System_Exception_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/InvalidPolylineException.cs#L43 + metadata: + uid: PolylineAlgorithm.InvalidPolylineException.#ctor(System.String,System.Exception) + commentId: M:PolylineAlgorithm.InvalidPolylineException.#ctor(System.String,System.Exception) +- markdown: Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. +- code: public InvalidPolylineException(string message, Exception innerException) +- h4: Parameters +- parameters: + - name: message + type: + - text: string + url: https://learn.microsoft.com/dotnet/api/system.string + description: The error message that explains the reason for the exception. + - name: innerException + type: + - text: Exception + url: https://learn.microsoft.com/dotnet/api/system.exception + description: The exception that is the cause of the current exception, or a null reference if no inner exception is specified. +languageId: csharp +metadata: + description: Exception thrown when a polyline is determined to be malformed or invalid during processing. diff --git a/api-reference/0.0/PolylineAlgorithm.PolylineEncoding.yml b/api-reference/0.0/PolylineAlgorithm.PolylineEncoding.yml new file mode 100644 index 00000000..a2e239f6 --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.PolylineEncoding.yml @@ -0,0 +1,529 @@ +### YamlMime:ApiPage +title: Class PolylineEncoding +body: +- api1: Class PolylineEncoding + id: PolylineAlgorithm_PolylineEncoding + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncoding.cs#L23 + metadata: + uid: PolylineAlgorithm.PolylineEncoding + commentId: T:PolylineAlgorithm.PolylineEncoding +- facts: + - name: Namespace + value: + text: PolylineAlgorithm + url: PolylineAlgorithm.html + - name: Assembly + value: PolylineAlgorithm.dll +- markdown: >- + Provides methods for encoding and decoding polyline data, as well as utilities for normalizing and de-normalizing + + geographic coordinate values. +- code: public static class PolylineEncoding +- h4: Inheritance +- inheritance: + - text: object + url: https://learn.microsoft.com/dotnet/api/system.object + - text: PolylineEncoding + url: PolylineAlgorithm.PolylineEncoding.html +- h4: Inherited Members +- list: + - text: object.Equals(object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object) + - text: object.Equals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object) + - text: object.GetHashCode() + url: https://learn.microsoft.com/dotnet/api/system.object.gethashcode + - text: object.GetType() + url: https://learn.microsoft.com/dotnet/api/system.object.gettype + - text: object.MemberwiseClone() + url: https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone + - text: object.ReferenceEquals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.referenceequals + - text: object.ToString() + url: https://learn.microsoft.com/dotnet/api/system.object.tostring +- h2: Remarks +- markdown: >- + The class includes functionality for working with encoded polyline + data, such as reading and writing encoded values, as well as methods for normalizing and de-normalizing geographic + coordinates. It also provides validation utilities to ensure values conform to expected ranges for latitude and + longitude. +- h2: Methods +- api3: Denormalize(int, uint) + id: PolylineAlgorithm_PolylineEncoding_Denormalize_System_Int32_System_UInt32_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncoding.cs#L122 + metadata: + uid: PolylineAlgorithm.PolylineEncoding.Denormalize(System.Int32,System.UInt32) + commentId: M:PolylineAlgorithm.PolylineEncoding.Denormalize(System.Int32,System.UInt32) +- markdown: Converts a normalized integer coordinate value back to its floating-point representation based on the specified precision. +- code: public static double Denormalize(int value, uint precision = 5) +- h4: Parameters +- parameters: + - name: value + type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + description: The integer value to denormalize. Typically produced by the method. + - name: precision + type: + - text: uint + url: https://learn.microsoft.com/dotnet/api/system.uint32 + description: The number of decimal places used during normalization. Default is 5, matching standard polyline encoding precision. + optional: true +- h4: Returns +- parameters: + - type: + - text: double + url: https://learn.microsoft.com/dotnet/api/system.double + description: The denormalized floating-point coordinate value. +- h4: Remarks +- markdown: >- +

+ + This method reverses the normalization performed by . It takes an integer value and converts it + + to a double by dividing it by 10 raised to the power of the specified precision. If precision is 0, + + the value is returned as a double without division. + +

+ +

+ + The calculation is performed inside a checked block to ensure that any arithmetic overflow is detected + + and an is thrown. + +

+ +

+ + For example, with a precision of 5: + + +

  • A value of 3778903 becomes 37.78903
  • A value of -12241230 becomes -122.4123
+ +

+ +

+ + If the input value is 0, the method returns 0.0 immediately. + +

+- h4: Exceptions +- parameters: + - type: + - text: OverflowException + url: https://learn.microsoft.com/dotnet/api/system.overflowexception + description: Thrown if the arithmetic operation overflows during conversion. +- api3: GetRequiredBufferSize(int) + id: PolylineAlgorithm_PolylineEncoding_GetRequiredBufferSize_System_Int32_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncoding.cs#L298 + metadata: + uid: PolylineAlgorithm.PolylineEncoding.GetRequiredBufferSize(System.Int32) + commentId: M:PolylineAlgorithm.PolylineEncoding.GetRequiredBufferSize(System.Int32) +- markdown: Calculates the number of characters required to encode a delta value in polyline format. +- code: public static int GetRequiredBufferSize(int delta) +- h4: Parameters +- parameters: + - name: delta + type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + description: >- + The integer delta value to calculate the encoded size for. This value typically represents the difference between + + consecutive coordinate values in polyline encoding. +- h4: Returns +- parameters: + - type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + description: The number of characters required to encode the specified delta value. The minimum return value is 1. +- h4: Remarks +- markdown: >- +

+ + This method determines how many characters will be needed to represent an integer delta value when encoded + + using the polyline encoding algorithm. It performs the same zigzag encoding transformation as + + but only calculates the required buffer size without actually writing any data. + +

+ +

+ + The calculation process: + + +

  1. Applies zigzag encoding: left-shifts the value by 1 bit, then inverts all bits if the original value was negative
  2. Counts how many 5-bit chunks are needed to represent the encoded value
  3. Each chunk requires one character, with a minimum of 1 character for any value
+ +

+ +

+ + This method is useful for pre-allocating buffers of the correct size before encoding polyline data, helping to avoid + + buffer overflow checks during the actual encoding process. + +

+ +

+ + The method uses a long internally to prevent overflow during the left-shift operation on large negative values. + +

+- h4: See Also +- list: + - - text: PolylineEncoding + url: PolylineAlgorithm.PolylineEncoding.html + - . + - text: TryWriteValue + url: PolylineAlgorithm.PolylineEncoding.html#PolylineAlgorithm_PolylineEncoding_TryWriteValue_System_Int32_System_Span_System_Char__System_Int32__ + - ( + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + - ',' + - " " + - text: Span + url: https://learn.microsoft.com/dotnet/api/system.span-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + - ',' + - " " + - ref + - " " + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + - ) +- api3: Normalize(double, uint) + id: PolylineAlgorithm_PolylineEncoding_Normalize_System_Double_System_UInt32_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncoding.cs#L61 + metadata: + uid: PolylineAlgorithm.PolylineEncoding.Normalize(System.Double,System.UInt32) + commentId: M:PolylineAlgorithm.PolylineEncoding.Normalize(System.Double,System.UInt32) +- markdown: Normalizes a geographic coordinate value to an integer representation based on the specified precision. +- code: public static int Normalize(double value, uint precision = 5) +- h4: Parameters +- parameters: + - name: value + type: + - text: double + url: https://learn.microsoft.com/dotnet/api/system.double + description: The numeric value to normalize. Must be a finite number (not NaN or infinity). + - name: precision + type: + - text: uint + url: https://learn.microsoft.com/dotnet/api/system.uint32 + description: >- + The number of decimal places of precision to preserve in the normalized value. + + The value is multiplied by 10^precision before rounding. + + Default is 5, which is standard for polyline encoding. + optional: true +- h4: Returns +- parameters: + - type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + description: An integer representing the normalized value. Returns 0 if the input value is 0.0. +- h4: Remarks +- markdown: >- +

+ + This method converts a floating-point coordinate value into a normalized integer by multiplying it by 10 raised + + to the power of the specified precision, then truncating the result to an integer. + +

+ +

+ + For example, with the default precision of 5: + + +

  • A value of 37.78903 becomes 3778903
  • A value of -122.4123 becomes -12241230
+ +

+ +

+ + The method validates that the input value is finite (not NaN or infinity) before performing normalization. + + If the precision is 0, the value is rounded without multiplication. + +

+- h4: Exceptions +- parameters: + - type: + - text: ArgumentOutOfRangeException + url: https://learn.microsoft.com/dotnet/api/system.argumentoutofrangeexception + description: Thrown when value is not a finite number (NaN or infinity). + - type: + - text: OverflowException + url: https://learn.microsoft.com/dotnet/api/system.overflowexception + description: Thrown when the normalized result exceeds the range of a 32-bit signed integer during the conversion from double to int. +- api3: TryReadValue(ref int, ReadOnlyMemory, ref int) + id: PolylineAlgorithm_PolylineEncoding_TryReadValue_System_Int32__System_ReadOnlyMemory_System_Char__System_Int32__ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncoding.cs#L169 + metadata: + uid: PolylineAlgorithm.PolylineEncoding.TryReadValue(System.Int32@,System.ReadOnlyMemory{System.Char},System.Int32@) + commentId: M:PolylineAlgorithm.PolylineEncoding.TryReadValue(System.Int32@,System.ReadOnlyMemory{System.Char},System.Int32@) +- markdown: Attempts to read an encoded integer value from a polyline buffer, updating the specified delta and position. +- code: public static bool TryReadValue(ref int delta, ReadOnlyMemory buffer, ref int position) +- h4: Parameters +- parameters: + - name: delta + type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + description: Reference to the integer accumulator that will be updated with the decoded value. + - name: buffer + type: + - text: ReadOnlyMemory + url: https://learn.microsoft.com/dotnet/api/system.readonlymemory-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + description: The buffer containing polyline-encoded characters. + - name: position + type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + description: Reference to the current position in the buffer. This value is updated as characters are read. +- h4: Returns +- parameters: + - type: + - text: bool + url: https://learn.microsoft.com/dotnet/api/system.boolean + description: true if a value was successfully read and decoded; false if the buffer ended before a complete value was read. +- h4: Remarks +- markdown: >- +

+ + This method decodes a value from a polyline-encoded character buffer, starting at the given position. It reads + + characters sequentially, applying the polyline decoding algorithm, and updates the delta with + + the decoded value. The position is advanced as characters are processed. + +

+ +

+ + The decoding process continues until a character with a value less than the algorithm's space constant is encountered, + + which signals the end of the encoded value. If the buffer is exhausted before a complete value is read, the method returns false. + +

+ +

+ + The decoded value is added to delta using zigzag decoding, which handles both positive and negative values. + +

+- api3: TryWriteValue(int, Span, ref int) + id: PolylineAlgorithm_PolylineEncoding_TryWriteValue_System_Int32_System_Span_System_Char__System_Int32__ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncoding.cs#L237 + metadata: + uid: PolylineAlgorithm.PolylineEncoding.TryWriteValue(System.Int32,System.Span{System.Char},System.Int32@) + commentId: M:PolylineAlgorithm.PolylineEncoding.TryWriteValue(System.Int32,System.Span{System.Char},System.Int32@) +- markdown: Attempts to write an encoded integer value to a polyline buffer, updating the specified position. +- code: public static bool TryWriteValue(int delta, Span buffer, ref int position) +- h4: Parameters +- parameters: + - name: delta + type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + description: >- + The integer value to encode and write to the buffer. This value typically represents the difference between consecutive + + coordinate values in polyline encoding. + - name: buffer + type: + - text: Span + url: https://learn.microsoft.com/dotnet/api/system.span-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + description: The destination buffer where the encoded characters will be written. Must have sufficient capacity to hold the encoded value. + - name: position + type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + description: >- + Reference to the current position in the buffer. This value is updated as characters are written to reflect the new position + + after encoding is complete. +- h4: Returns +- parameters: + - type: + - text: bool + url: https://learn.microsoft.com/dotnet/api/system.boolean + description: >- + true if the value was successfully encoded and written to the buffer; false if the buffer + + does not have sufficient remaining capacity to hold the encoded value. +- h4: Remarks +- markdown: >- +

+ + This method encodes an integer delta value into a polyline-encoded format and writes it to the provided character buffer, + + starting at the given position. It applies zigzag encoding followed by the polyline encoding algorithm to represent + + both positive and negative values efficiently. + +

+ +

+ + The encoding process first converts the value using zigzag encoding (left shift by 1, with bitwise inversion for negative values), + + then writes it as a sequence of characters. Each character encodes 5 bits of data, with continuation bits indicating whether + + more characters follow. The position is advanced as characters are written. + +

+ +

+ + Before writing, the method validates that sufficient space is available in the buffer by calling . + + If the buffer does not have enough remaining capacity, the method returns false without modifying the buffer or position. + +

+ +

+ + This method is the inverse of and can be used to encode coordinate deltas for polyline serialization. + +

+- api3: ValidateBlockLength(ReadOnlySpan) + id: PolylineAlgorithm_PolylineEncoding_ValidateBlockLength_System_ReadOnlySpan_System_Char__ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncoding.cs#L438 + metadata: + uid: PolylineAlgorithm.PolylineEncoding.ValidateBlockLength(System.ReadOnlySpan{System.Char}) + commentId: M:PolylineAlgorithm.PolylineEncoding.ValidateBlockLength(System.ReadOnlySpan{System.Char}) +- markdown: Validates the block structure of a polyline segment, ensuring each encoded value does not exceed 7 characters and the polyline ends correctly. +- code: public static void ValidateBlockLength(ReadOnlySpan polyline) +- h4: Parameters +- parameters: + - name: polyline + type: + - text: ReadOnlySpan + url: https://learn.microsoft.com/dotnet/api/system.readonlyspan-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + description: A span representing the polyline segment to validate. +- h4: Remarks +- markdown: >- +

+ + Iterates through the polyline, counting the length of each block (a sequence of characters representing an encoded value). + + Throws an if any block exceeds 7 characters or if the polyline does not end with a valid block terminator. + +

+- h4: Exceptions +- parameters: + - type: + - text: ArgumentException + url: https://learn.microsoft.com/dotnet/api/system.argumentexception + description: Thrown when a block exceeds 7 characters or the polyline does not end with a valid block terminator. +- api3: ValidateCharRange(ReadOnlySpan) + id: PolylineAlgorithm_PolylineEncoding_ValidateCharRange_System_ReadOnlySpan_System_Char__ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncoding.cs#L392 + metadata: + uid: PolylineAlgorithm.PolylineEncoding.ValidateCharRange(System.ReadOnlySpan{System.Char}) + commentId: M:PolylineAlgorithm.PolylineEncoding.ValidateCharRange(System.ReadOnlySpan{System.Char}) +- markdown: Validates that all characters in the polyline segment are within the allowed ASCII range for polyline encoding. +- code: public static void ValidateCharRange(ReadOnlySpan polyline) +- h4: Parameters +- parameters: + - name: polyline + type: + - text: ReadOnlySpan + url: https://learn.microsoft.com/dotnet/api/system.readonlyspan-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + description: A span representing the polyline segment to validate. +- h4: Remarks +- markdown: >- +

+ + Uses SIMD vectorization for efficient validation of large spans. Falls back to scalar checks for any block where an invalid character is detected. + +

+ +

+ + The valid range is from '?' (63) to '_' (95), inclusive. If an invalid character is found, an is thrown. + +

+- h4: Exceptions +- parameters: + - type: + - text: ArgumentException + url: https://learn.microsoft.com/dotnet/api/system.argumentexception + description: Thrown when an invalid character is found in the polyline segment. +- api3: ValidateFormat(ReadOnlySpan) + id: PolylineAlgorithm_PolylineEncoding_ValidateFormat_System_ReadOnlySpan_System_Char__ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncoding.cs#L370 + metadata: + uid: PolylineAlgorithm.PolylineEncoding.ValidateFormat(System.ReadOnlySpan{System.Char}) + commentId: M:PolylineAlgorithm.PolylineEncoding.ValidateFormat(System.ReadOnlySpan{System.Char}) +- markdown: Validates the format of a polyline segment, ensuring all characters are valid and block structure is correct. +- code: public static void ValidateFormat(ReadOnlySpan polyline) +- h4: Parameters +- parameters: + - name: polyline + type: + - text: ReadOnlySpan + url: https://learn.microsoft.com/dotnet/api/system.readonlyspan-1 + - < + - text: char + url: https://learn.microsoft.com/dotnet/api/system.char + - '>' + description: A span representing the polyline segment to validate. +- h4: Remarks +- markdown: >- +

+ + This method performs two levels of validation on the provided polyline segment: + +

+ +
  1. + Character Range Validation: Checks that every character in the polyline is within the valid ASCII range for polyline encoding ('?' [63] to '_' [95], inclusive). + Uses SIMD acceleration for efficient validation of large segments. +
  2. + Block Structure Validation: Ensures that each encoded value (block) does not exceed 7 characters and that the polyline ends with a valid block terminator. +
+

+ + If an invalid character or block structure is detected, an is thrown with details about the error. + +

+- h4: Exceptions +- parameters: + - type: + - text: ArgumentException + url: https://learn.microsoft.com/dotnet/api/system.argumentexception + description: Thrown when an invalid character is found or the block structure is invalid. +languageId: csharp +metadata: + description: >- + Provides methods for encoding and decoding polyline data, as well as utilities for normalizing and de-normalizing + + geographic coordinate values. diff --git a/api-reference/0.0/PolylineAlgorithm.PolylineEncodingOptions.yml b/api-reference/0.0/PolylineAlgorithm.PolylineEncodingOptions.yml new file mode 100644 index 00000000..a3870dbd --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.PolylineEncodingOptions.yml @@ -0,0 +1,127 @@ +### YamlMime:ApiPage +title: Class PolylineEncodingOptions +body: +- api1: Class PolylineEncodingOptions + id: PolylineAlgorithm_PolylineEncodingOptions + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptions.cs#L29 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptions + commentId: T:PolylineAlgorithm.PolylineEncodingOptions +- facts: + - name: Namespace + value: + text: PolylineAlgorithm + url: PolylineAlgorithm.html + - name: Assembly + value: PolylineAlgorithm.dll +- markdown: Provides configuration options for polyline encoding operations. +- code: public sealed class PolylineEncodingOptions +- h4: Inheritance +- inheritance: + - text: object + url: https://learn.microsoft.com/dotnet/api/system.object + - text: PolylineEncodingOptions + url: PolylineAlgorithm.PolylineEncodingOptions.html +- h4: Inherited Members +- list: + - text: object.Equals(object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object) + - text: object.Equals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object) + - text: object.GetHashCode() + url: https://learn.microsoft.com/dotnet/api/system.object.gethashcode + - text: object.GetType() + url: https://learn.microsoft.com/dotnet/api/system.object.gettype + - text: object.ReferenceEquals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.referenceequals + - text: object.ToString() + url: https://learn.microsoft.com/dotnet/api/system.object.tostring +- h2: Remarks +- markdown: >- +

+ + This class allows you to configure various aspects of polyline encoding, including: + +

+ +
  • The level for coordinate encoding
  • The for memory allocation strategy
  • The for diagnostic logging
+ +

+ + All properties have internal setters and should be configured through a builder or factory pattern. + +

+- h2: Properties +- api3: LoggerFactory + id: PolylineAlgorithm_PolylineEncodingOptions_LoggerFactory + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptions.cs#L41 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptions.LoggerFactory + commentId: P:PolylineAlgorithm.PolylineEncodingOptions.LoggerFactory +- markdown: Gets the logger factory used for diagnostic logging during encoding operations. +- code: public ILoggerFactory LoggerFactory { get; } +- h4: Property Value +- parameters: + - type: + - text: ILoggerFactory + url: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerfactory +- h4: Remarks +- markdown: >- + The default logger factory is , which does not log any messages. + + To enable logging, provide a custom implementation. +- api3: Precision + id: PolylineAlgorithm_PolylineEncodingOptions_Precision + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptions.cs#L60 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptions.Precision + commentId: P:PolylineAlgorithm.PolylineEncodingOptions.Precision +- markdown: Gets the precision level used for encoding coordinate values. +- code: public uint Precision { get; } +- h4: Property Value +- parameters: + - type: + - text: uint + url: https://learn.microsoft.com/dotnet/api/system.uint32 +- h4: Remarks +- markdown: >- +

+ + The precision determines the number of decimal places to which each coordinate value (latitude or longitude) + + is multiplied and truncated (not rounded) before encoding. For example, a precision of 5 means each coordinate is multiplied by 10^5 + + and truncated to an integer before encoding. + +

+ +

+ + This setting does not directly correspond to a physical distance or accuracy in meters, but rather controls + + the granularity of the encoded values. + +

+- api3: StackAllocLimit + id: PolylineAlgorithm_PolylineEncodingOptions_StackAllocLimit + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptions.cs#L73 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptions.StackAllocLimit + commentId: P:PolylineAlgorithm.PolylineEncodingOptions.StackAllocLimit +- markdown: Gets the maximum buffer size (in characters) that can be allocated on the stack for encoding operations. +- code: public int StackAllocLimit { get; } +- h4: Property Value +- parameters: + - type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 +- h4: Remarks +- markdown: >- + When the required buffer size for encoding exceeds this limit, memory will be allocated on the heap instead of the stack. + + This setting specifically applies to stack allocation of character arrays (stackalloc char[]) used during polyline encoding, + + balancing performance and stack safety. +languageId: csharp +metadata: + description: Provides configuration options for polyline encoding operations. diff --git a/api-reference/0.0/PolylineAlgorithm.PolylineEncodingOptionsBuilder.yml b/api-reference/0.0/PolylineAlgorithm.PolylineEncodingOptionsBuilder.yml new file mode 100644 index 00000000..3cffbdce --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.PolylineEncodingOptionsBuilder.yml @@ -0,0 +1,141 @@ +### YamlMime:ApiPage +title: Class PolylineEncodingOptionsBuilder +body: +- api1: Class PolylineEncodingOptionsBuilder + id: PolylineAlgorithm_PolylineEncodingOptionsBuilder + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptionsBuilder.cs#L15 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptionsBuilder + commentId: T:PolylineAlgorithm.PolylineEncodingOptionsBuilder +- facts: + - name: Namespace + value: + text: PolylineAlgorithm + url: PolylineAlgorithm.html + - name: Assembly + value: PolylineAlgorithm.dll +- markdown: Provides a builder for configuring options for polyline encoding operations. +- code: public sealed class PolylineEncodingOptionsBuilder +- h4: Inheritance +- inheritance: + - text: object + url: https://learn.microsoft.com/dotnet/api/system.object + - text: PolylineEncodingOptionsBuilder + url: PolylineAlgorithm.PolylineEncodingOptionsBuilder.html +- h4: Inherited Members +- list: + - text: object.Equals(object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object) + - text: object.Equals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object) + - text: object.GetHashCode() + url: https://learn.microsoft.com/dotnet/api/system.object.gethashcode + - text: object.GetType() + url: https://learn.microsoft.com/dotnet/api/system.object.gettype + - text: object.ReferenceEquals(object, object) + url: https://learn.microsoft.com/dotnet/api/system.object.referenceequals + - text: object.ToString() + url: https://learn.microsoft.com/dotnet/api/system.object.tostring +- h2: Methods +- api3: Build() + id: PolylineAlgorithm_PolylineEncodingOptionsBuilder_Build + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptionsBuilder.cs#L38 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptionsBuilder.Build + commentId: M:PolylineAlgorithm.PolylineEncodingOptionsBuilder.Build +- markdown: Builds a new instance using the configured options. +- code: public PolylineEncodingOptions Build() +- h4: Returns +- parameters: + - type: + - text: PolylineEncodingOptions + url: PolylineAlgorithm.PolylineEncodingOptions.html + description: A configured instance. +- api3: Create() + id: PolylineAlgorithm_PolylineEncodingOptionsBuilder_Create + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptionsBuilder.cs#L28 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptionsBuilder.Create + commentId: M:PolylineAlgorithm.PolylineEncodingOptionsBuilder.Create +- markdown: Creates a new instance for the specified coordinate type. +- code: public static PolylineEncodingOptionsBuilder Create() +- h4: Returns +- parameters: + - type: + - text: PolylineEncodingOptionsBuilder + url: PolylineAlgorithm.PolylineEncodingOptionsBuilder.html + description: An instance for configuring polyline encoding options. +- api3: WithLoggerFactory(ILoggerFactory) + id: PolylineAlgorithm_PolylineEncodingOptionsBuilder_WithLoggerFactory_Microsoft_Extensions_Logging_ILoggerFactory_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptionsBuilder.cs#L97 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptionsBuilder.WithLoggerFactory(Microsoft.Extensions.Logging.ILoggerFactory) + commentId: M:PolylineAlgorithm.PolylineEncodingOptionsBuilder.WithLoggerFactory(Microsoft.Extensions.Logging.ILoggerFactory) +- markdown: Configures the to be used for logging during polyline encoding operations. +- code: public PolylineEncodingOptionsBuilder WithLoggerFactory(ILoggerFactory loggerFactory) +- h4: Parameters +- parameters: + - name: loggerFactory + type: + - text: ILoggerFactory + url: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerfactory + description: The instance to use for logging. If null, a will be used instead. +- h4: Returns +- parameters: + - type: + - text: PolylineEncodingOptionsBuilder + url: PolylineAlgorithm.PolylineEncodingOptionsBuilder.html + description: The current instance for method chaining. +- api3: WithPrecision(uint) + id: PolylineAlgorithm_PolylineEncodingOptionsBuilder_WithPrecision_System_UInt32_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptionsBuilder.cs#L82 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptionsBuilder.WithPrecision(System.UInt32) + commentId: M:PolylineAlgorithm.PolylineEncodingOptionsBuilder.WithPrecision(System.UInt32) +- markdown: Sets the coordinate encoding precision. +- code: public PolylineEncodingOptionsBuilder WithPrecision(uint precision) +- h4: Parameters +- parameters: + - name: precision + type: + - text: uint + url: https://learn.microsoft.com/dotnet/api/system.uint32 + description: The number of decimal places to use for encoding coordinate values. Default is 5. +- h4: Returns +- parameters: + - type: + - text: PolylineEncodingOptionsBuilder + url: PolylineAlgorithm.PolylineEncodingOptionsBuilder.html + description: The current instance for method chaining. +- api3: WithStackAllocLimit(int) + id: PolylineAlgorithm_PolylineEncodingOptionsBuilder_WithStackAllocLimit_System_Int32_ + src: https://github.com/petesramek/polyline-algorithm-csharp/blob/bugfix/incorrect-normalization/src/PolylineAlgorithm/PolylineEncodingOptionsBuilder.cs#L61 + metadata: + uid: PolylineAlgorithm.PolylineEncodingOptionsBuilder.WithStackAllocLimit(System.Int32) + commentId: M:PolylineAlgorithm.PolylineEncodingOptionsBuilder.WithStackAllocLimit(System.Int32) +- markdown: Configures the buffer size used for stack allocation during polyline encoding operations. +- code: public PolylineEncodingOptionsBuilder WithStackAllocLimit(int stackAllocLimit) +- h4: Parameters +- parameters: + - name: stackAllocLimit + type: + - text: int + url: https://learn.microsoft.com/dotnet/api/system.int32 + description: The maximum buffer size to use for stack allocation. Must be greater than or equal to 1. +- h4: Returns +- parameters: + - type: + - text: PolylineEncodingOptionsBuilder + url: PolylineAlgorithm.PolylineEncodingOptionsBuilder.html + description: The current instance for method chaining. +- h4: Remarks +- markdown: This method allows customization of the internal buffer size for encoding, which can impact performance and memory usage. +- h4: Exceptions +- parameters: + - type: + - text: ArgumentOutOfRangeException + url: https://learn.microsoft.com/dotnet/api/system.argumentoutofrangeexception + description: Thrown if stackAllocLimit is less than 1. +languageId: csharp +metadata: + description: Provides a builder for configuring options for polyline encoding operations. diff --git a/api-reference/0.0/PolylineAlgorithm.yml b/api-reference/0.0/PolylineAlgorithm.yml new file mode 100644 index 00000000..b60dc3c0 --- /dev/null +++ b/api-reference/0.0/PolylineAlgorithm.yml @@ -0,0 +1,38 @@ +### YamlMime:ApiPage +title: Namespace PolylineAlgorithm +body: +- api1: Namespace PolylineAlgorithm + id: PolylineAlgorithm + metadata: + uid: PolylineAlgorithm + commentId: N:PolylineAlgorithm +- h3: Namespaces +- parameters: + - type: + text: PolylineAlgorithm.Abstraction + url: PolylineAlgorithm.Abstraction.html + - type: + text: PolylineAlgorithm.Extensions + url: PolylineAlgorithm.Extensions.html +- h3: Classes +- parameters: + - type: + text: InvalidPolylineException + url: PolylineAlgorithm.InvalidPolylineException.html + description: Exception thrown when a polyline is determined to be malformed or invalid during processing. + - type: + text: PolylineEncoding + url: PolylineAlgorithm.PolylineEncoding.html + description: >- + Provides methods for encoding and decoding polyline data, as well as utilities for normalizing and de-normalizing + + geographic coordinate values. + - type: + text: PolylineEncodingOptions + url: PolylineAlgorithm.PolylineEncodingOptions.html + description: Provides configuration options for polyline encoding operations. + - type: + text: PolylineEncodingOptionsBuilder + url: PolylineAlgorithm.PolylineEncodingOptionsBuilder.html + description: Provides a builder for configuring options for polyline encoding operations. +languageId: csharp diff --git a/api-reference/0.0/toc.yml b/api-reference/0.0/toc.yml new file mode 100644 index 00000000..d1ffc58a --- /dev/null +++ b/api-reference/0.0/toc.yml @@ -0,0 +1,34 @@ +### YamlMime:TableOfContent +- name: PolylineAlgorithm + href: PolylineAlgorithm.yml + items: + - name: Classes + - name: InvalidPolylineException + href: PolylineAlgorithm.InvalidPolylineException.yml + - name: PolylineEncoding + href: PolylineAlgorithm.PolylineEncoding.yml + - name: PolylineEncodingOptions + href: PolylineAlgorithm.PolylineEncodingOptions.yml + - name: PolylineEncodingOptionsBuilder + href: PolylineAlgorithm.PolylineEncodingOptionsBuilder.yml +- name: PolylineAlgorithm.Abstraction + href: PolylineAlgorithm.Abstraction.yml + items: + - name: Classes + - name: AbstractPolylineDecoder + href: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.yml + - name: AbstractPolylineEncoder + href: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.yml + - name: Interfaces + - name: IPolylineDecoder + href: PolylineAlgorithm.Abstraction.IPolylineDecoder-2.yml + - name: IPolylineEncoder + href: PolylineAlgorithm.Abstraction.IPolylineEncoder-2.yml +- name: PolylineAlgorithm.Extensions + href: PolylineAlgorithm.Extensions.yml + items: + - name: Classes + - name: PolylineDecoderExtensions + href: PolylineAlgorithm.Extensions.PolylineDecoderExtensions.yml + - name: PolylineEncoderExtensions + href: PolylineAlgorithm.Extensions.PolylineEncoderExtensions.yml diff --git a/src/PolylineAlgorithm/PolylineEncoding.cs b/src/PolylineAlgorithm/PolylineEncoding.cs index 4b8d5312..3d6de5e7 100644 --- a/src/PolylineAlgorithm/PolylineEncoding.cs +++ b/src/PolylineAlgorithm/PolylineEncoding.cs @@ -1,4 +1,4 @@ -// +// // Copyright © Pete Sramek. All rights reserved. // Licensed under the MIT License. See LICENSE file in the project root for full license information. // @@ -76,10 +76,11 @@ public static int Normalize(double value, uint precision = 5) { uint factor = Pow10.GetFactor(precision); + const double Epsilon = 1e-9; + checked { - return (int)(Math.Truncate(value * 10 * factor) / 10); + return (int)Math.Truncate((value * factor) + (Epsilon * Math.Sign(value))); } - } ///