diff --git a/.editorconfig b/.editorconfig index 75d9084f..7282c0f7 100644 --- a/.editorconfig +++ b/.editorconfig @@ -274,3 +274,6 @@ dotnet_naming_style.underscore_camel_case.capitalization = camel_case # Public API analyzer dotnet_public_api_analyzer.require_api_files = true + +# RS0017: Symbol removed from public API - error severity (IDE guidance; build enforcement via WarningsAsErrors in .csproj) +dotnet_diagnostic.RS0017.severity = error diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..880b45f7 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,5 @@ +* @petesramek + +.github/ @petesramek +src/ @petesramek +tests/ @petesramek diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index dd84ea78..6236e3a0 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,8 +1,8 @@ --- name: Bug report about: Create a report to help us improve -title: '' -labels: '' +title: '[Bug]: ' +labels: 'bug' assignees: '' --- @@ -11,28 +11,22 @@ assignees: '' A clear and concise description of what the bug is. **To Reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error +Minimal code snippet that reproduces the issue: + +```csharp +// paste reproduction code here +``` **Expected behavior** A clear and concise description of what you expected to happen. -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**Desktop (please complete the following information):** - - OS: [e.g. iOS] - - Browser [e.g. chrome, safari] - - Version [e.g. 22] +**Actual behavior** +A clear and concise description of what actually happens (include exception messages/stack traces if applicable). -**Smartphone (please complete the following information):** - - Device: [e.g. iPhone6] - - OS: [e.g. iOS8.1] - - Browser [e.g. stock browser, safari] - - Version [e.g. 22] +**Environment** + - Package version: [e.g. 2.1.0] + - .NET version: [e.g. net8.0] + - OS: [e.g. Windows 11, Ubuntu 24.04] **Additional context** Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..2afb950d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Ask a question + url: https://github.com/petesramek/polyline-algorithm-csharp/discussions + about: Use GitHub Discussions for questions, ideas, or general feedback. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bbcbbe7d..5c8a425a 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,8 +1,8 @@ --- name: Feature request about: Suggest an idea for this project -title: '' -labels: '' +title: '[Feature]: ' +labels: 'enhancement' assignees: '' --- diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..70eda657 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## Summary + + + +## Type of change + +- [ ] Bug fix +- [ ] New feature +- [ ] Breaking change +- [ ] Documentation / samples only + +## Checklist + +- [ ] Unit tests added or updated (`/tests`) +- [ ] Benchmarks added or updated (`/benchmarks`) — if performance-impacting +- [ ] XML doc comments updated for all public API changes +- [ ] `dotnet format` run with no issues +- [ ] README and `/samples` updated — if public API changed +- [ ] PR label added (`breaking` / `feat` / `fix` / `docs`) — for changelog categorization diff --git a/.github/actions/source/compile/action.yml b/.github/actions/source/compile/action.yml index 0af331ee..dbe88dd5 100644 --- a/.github/actions/source/compile/action.yml +++ b/.github/actions/source/compile/action.yml @@ -12,7 +12,7 @@ inputs: file-version: description: 'Assembly file version.' required: true - treat-warnins-as-error: + treat-warnings-as-error: description: 'Treat warnings as errors.' required: true project-path: diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 02a54502..b00ae422 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -4,11 +4,23 @@ updates: directory: "/" schedule: interval: "weekly" + labels: + - "dependencies" + assignees: + - "petesramek" - package-ecosystem: "nuget" directory: "/" schedule: interval: "weekly" + labels: + - "dependencies" + assignees: + - "petesramek" - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly" + labels: + - "dependencies" + assignees: + - "petesramek" diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 00000000..e7b05735 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,23 @@ +changelog: + exclude: + labels: + - ignore-for-release + categories: + - title: Breaking Changes + labels: + - breaking + - title: New Features + labels: + - feat + - enhancement + - title: Bug Fixes + labels: + - fix + - bug + - title: Documentation + labels: + - docs + - documentation + - title: Other Changes + labels: + - '*' diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 047d4afd..5abb7df8 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -130,7 +130,7 @@ jobs: assembly-version: ${{ env.assembly-version }} assembly-informational-version: ${{ env.assembly-informational-version }} file-version: ${{ env.file-version }} - treat-warnins-as-error: ${{ needs.workflow-variables.outputs.is-release }} + treat-warnings-as-error: ${{ needs.workflow-variables.outputs.is-release }} test: name: 'Run tests' diff --git a/.github/workflows/publish-documentation.yml b/.github/workflows/publish-documentation.yml index 85d8f21a..7f01504d 100644 --- a/.github/workflows/publish-documentation.yml +++ b/.github/workflows/publish-documentation.yml @@ -96,6 +96,21 @@ jobs: run: | cp -r api-reference/guide api-reference/${{ env.friendly-version }}/guide + - name: 'Download benchmark results' + uses: actions/download-artifact@v8 + with: + pattern: benchmark-* + path: /tmp/benchmarks + merge-multiple: true + + - name: 'Inject benchmark results into guide for v${{ env.friendly-version }}' + shell: bash + run: | + find /tmp/benchmarks -name "*-report-github.md" | sort | xargs -r cat > /tmp/benchmark_results.md + awk '/{benchmarks_section}/{while((getline line < "/tmp/benchmark_results.md") > 0) print line; close("/tmp/benchmark_results.md"); next} {print}' \ + "api-reference/${{ env.friendly-version }}/guide/benchmarks.md" > /tmp/benchmarks.md + mv /tmp/benchmarks.md "api-reference/${{ env.friendly-version }}/guide/benchmarks.md" + - name: 'Discover all versions' id: discover-versions shell: bash @@ -151,15 +166,15 @@ jobs: { echo "## Released Versions" echo "" - echo "| Version | Guide | API Reference |" - echo "|---------|-------|---------------|" + echo "| Version | Guide | API Reference | Release Notes |" + echo "|---------|-------|---------------|---------------|" for ver in $(echo "${{ steps.discover-versions.outputs.versions }}" | tr ',' '\n' | sort -Vr); do if [ "$ver" = "$latest" ]; then label="v${ver} (latest)" else label="v${ver}" fi - echo "| ${label} | [Guide](${ver}/guide/getting-started.html) | [API Reference](${ver}/PolylineAlgorithm.html) |" + echo "| ${label} | [Guide](${ver}/guide/getting-started.html) | [API Reference](${ver}/PolylineAlgorithm.html) | [Release Notes](https://github.com/petesramek/polyline-algorithm-csharp/releases/tag/v${ver}) |" done } > /tmp/versions_section.md awk '/{versions_section}/{while((getline line < "/tmp/versions_section.md") > 0) print line; close("/tmp/versions_section.md"); next} {print}' \ diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 4f8917b0..c99f254d 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -18,8 +18,8 @@ permissions: id-token: write contents: write -concurrency: - group: pull-request-${{ github.head_ref || github.ref }} +concurrency: + group: pull-request-${{ github.head_ref || github.ref }} cancel-in-progress: true env: @@ -120,7 +120,7 @@ jobs: assembly-version: ${{ env.assembly-version }} assembly-informational-version: ${{ env.assembly-informational-version }} file-version: ${{ env.file-version }} - treat-warnins-as-error: ${{ needs.workflow-variables.outputs.is-release }} + treat-warnings-as-error: ${{ needs.workflow-variables.outputs.is-release }} test: name: 'Run tests' @@ -189,7 +189,7 @@ jobs: - name: Pack with .NET run: | dotnet pack ${{ vars.SRC_DEFAULT_GLOB_PATTERN }} --configuration ${{ env.build-configuration }} /p:Platform="${{ env.build-platform }}" /p:PackageVersion=${{ env.release-version }} /p:Version=${{ env.assembly-version }} /p:AssemblyInformationalVersion=${{ env.assembly-informational-version }} /p:FileVersion=${{ env.file-version }} --output ${{ runner.temp }}/${{ env.nuget-packages-directory }} - + - name: Upload Package uses: actions/upload-artifact@v7 with: @@ -222,39 +222,20 @@ jobs: nuget-feed-api-key: ${{ secrets.NUGET_PACKAGE_FEED_API_KEY }} nuget-feed-server: 'AzureArtifacts' working-directory: ${{ runner.temp }}/${{ env.nuget-packages-directory }} - dotnet-sdk-version: ${{ env.dotnet-sdk-version }}' + dotnet-sdk-version: ${{ env.dotnet-sdk-version }} - benchmark: - if: ${{ github.env.is_release || vars.BENCHMARKDOTNET_RUN_OVERRIDE == 'true' }} - name: Benchmark with .NET CLI on ${{ matrix.os }} + security: + name: 'Check for vulnerable packages' needs: [build] - strategy: - matrix: - os: [ubuntu-latest, windows-latest, macos-latest] - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: 'Checkout ${{ github.head_ref || github.ref }}' uses: actions/checkout@v6 - - name: Install .NET SDK + + - name: 'Setup .NET' uses: actions/setup-dotnet@v5 with: - dotnet-version: | - 8.x - 10.x - - name: Download Build - uses: actions/download-artifact@v8 - with: - name: build - - name: Benchmark - working-directory: ${{ vars.BENCHMARKDOTNET_WORKING_DIRECTORY }} - run: dotnet run --configuration ${{ env.build-configuration }} /p:Platform=${{ env.build-platform }} --framework ${{ vars.DEFAULT_BUILD_FRAMEWORK }} --runtimes ${{ vars.BENCHMARKDOTNET_RUNTIMES }} --filter ${{ vars.BENCHMARKDOTNET_FILTER }} --artifacts ${{ runner.temp }}/benchmarks/ --exporters GitHub --memory --iterationTime 100 --join - - name: Upload Benchmark Results - uses: actions/upload-artifact@v7 - with: - name: benchmark-${{ matrix.os }} - path: | - ${{ runner.temp }}/benchmarks/**/*-report-github.md - - name: Write Benchmark Summary - shell: bash - run: cat **/*-report-github.md > $GITHUB_STEP_SUMMARY - working-directory: ${{ runner.temp }}/benchmarks/ + dotnet-version: ${{ env.dotnet-sdk-version }} + + - name: 'Check for vulnerable packages' + run: dotnet list src/PolylineAlgorithm/PolylineAlgorithm.csproj package --vulnerable --include-transitive diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0d2808a8..b0bd5699 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -129,7 +129,7 @@ jobs: assembly-version: ${{ env.assembly-version }} assembly-informational-version: ${{ env.assembly-informational-version }} file-version: ${{ env.file-version }} - treat-warnins-as-error: ${{ needs.workflow-variables.outputs.is-release }} + treat-warnings-as-error: ${{ needs.workflow-variables.outputs.is-release }} test: name: 'Run tests' @@ -169,6 +169,89 @@ jobs: - name: Write code coverage report summary run: cat ${{ steps.code-coverage-report.outputs.code-coverage-report-file }} >> $GITHUB_STEP_SUMMARY + update-api-unshipped: + name: 'Update PublicAPI.Unshipped.txt' + needs: [workflow-variables, validate-release] + # Run even when build fails — the build may fail solely because a dropped preview API is still + # listed in Unshipped.txt (RS0017). This job fixes exactly that, so it must not be gated on build. + if: ${{ needs.workflow-variables.outputs.is-preview == 'true' && needs.validate-release.result == 'success' }} + runs-on: ubuntu-latest + steps: + - name: 'Checkout ${{ github.ref }}' + uses: actions/checkout@v6 + + - name: 'Setup .NET' + uses: actions/setup-dotnet@v5 + with: + dotnet-version: ${{ env.dotnet-sdk-version }} + + - name: 'Snapshot PublicAPI.Shipped.txt' + shell: bash + run: cp src/PolylineAlgorithm/PublicAPI.Shipped.txt src/PolylineAlgorithm/PublicAPI.Shipped.txt.bak + + - name: 'Sync PublicAPI.Unshipped.txt (add new + remove dropped preview APIs)' + shell: bash + run: dotnet format analyzers src/PolylineAlgorithm/PolylineAlgorithm.csproj --diagnostics RS0016 RS0017 + + - name: 'Guard against accidental shipped API removal' + shell: bash + run: | + SHIPPED="src/PolylineAlgorithm/PublicAPI.Shipped.txt" + if ! diff -q "$SHIPPED" "$SHIPPED.bak" > /dev/null 2>&1; then + echo "::error::Breaking change detected — a shipped API was removed from PublicAPI.Shipped.txt." + echo "::error::This requires a major version bump. Reverting the unintended change." + cp "$SHIPPED.bak" "$SHIPPED" + exit 1 + fi + rm -f "$SHIPPED.bak" + + - name: 'Configure git identity' + uses: './.github/actions/git/configure-identity' + + - name: 'Commit and push updated API files' + shell: bash + run: | + git add src/PolylineAlgorithm/PublicAPI.Unshipped.txt + git diff --staged --quiet || ( + git commit -m "Sync PublicAPI.Unshipped.txt (add new, remove dropped preview APIs)" && + git pull --rebase origin ${{ github.ref_name }} && + git push + ) + + promote-api-files: + name: 'Promote PublicAPI files (Unshipped -> Shipped)' + needs: [workflow-variables, test, validate-release] + if: ${{ needs.workflow-variables.outputs.is-release == 'true' }} + runs-on: ubuntu-latest + steps: + - name: 'Checkout ${{ github.ref }}' + uses: actions/checkout@v6 + + - name: 'Promote Unshipped.txt into Shipped.txt' + shell: bash + run: | + UNSHIPPED="src/PolylineAlgorithm/PublicAPI.Unshipped.txt" + SHIPPED="src/PolylineAlgorithm/PublicAPI.Shipped.txt" + + # Append every non-blank, non-header line from Unshipped into Shipped + tail -n +2 "$UNSHIPPED" | grep -v '^[[:space:]]*$' >> "$SHIPPED" || true + + # Reset Unshipped to just the nullable-enable header (with BOM to match convention) + printf '\xef\xbb\xbf#nullable enable\n' > "$UNSHIPPED" + + - name: 'Configure git identity' + uses: './.github/actions/git/configure-identity' + + - name: 'Commit and push promoted API files' + shell: bash + run: | + git add src/PolylineAlgorithm/PublicAPI.Shipped.txt src/PolylineAlgorithm/PublicAPI.Unshipped.txt + git diff --staged --quiet || ( + git commit -m "Promote PublicAPI.Unshipped.txt into PublicAPI.Shipped.txt for release" && + git pull --rebase origin ${{ github.ref_name }} && + git push + ) + pack: name: 'Package binaries' needs: [versioning, build, test, validate-release] @@ -207,9 +290,44 @@ jobs: ${{ runner.temp }}/${{ env.nuget-packages-directory }}/**/*.nupkg ${{ runner.temp }}/${{ env.nuget-packages-directory }}/**/*.snupkg + benchmark: + name: Benchmark with .NET CLI on ${{ matrix.os }} + needs: [workflow-variables, build, validate-release] + if: ${{ needs.workflow-variables.outputs.is-release == 'true' || vars.BENCHMARKDOTNET_RUN_OVERRIDE == 'true' }} + strategy: + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + runs-on: ${{ matrix.os }} + steps: + - name: 'Checkout ${{ github.head_ref || github.ref }}' + uses: actions/checkout@v6 + - name: Install .NET SDK + uses: actions/setup-dotnet@v5 + with: + dotnet-version: | + 8.x + 10.x + - name: Download Build + uses: actions/download-artifact@v8 + with: + name: build + - name: Benchmark + working-directory: ${{ vars.BENCHMARKDOTNET_WORKING_DIRECTORY }} + run: dotnet run --configuration ${{ env.build-configuration }} /p:Platform=${{ env.build-platform }} --framework ${{ vars.DEFAULT_BUILD_FRAMEWORK }} --runtimes ${{ vars.BENCHMARKDOTNET_RUNTIMES }} --filter ${{ vars.BENCHMARKDOTNET_FILTER }} --artifacts ${{ runner.temp }}/benchmarks/ --exporters GitHub --memory --iterationTime 100 --join + - name: Upload Benchmark Results + uses: actions/upload-artifact@v7 + with: + name: benchmark-${{ matrix.os }} + path: | + ${{ runner.temp }}/benchmarks/**/*-report-github.md + - name: Write Benchmark Summary + shell: bash + run: cat **/*-report-github.md > $GITHUB_STEP_SUMMARY + working-directory: ${{ runner.temp }}/benchmarks/ + publish-documentation: name: 'Publish documentation' - needs: [pack, validate-release, workflow-variables] + needs: [pack, benchmark, validate-release, workflow-variables] if: ${{ needs.workflow-variables.outputs.is-release == 'true' }} uses: ./.github/workflows/publish-documentation.yml permissions: @@ -219,8 +337,14 @@ jobs: publish-package: name: 'Publish package' - needs: [pack, validate-release, publish-documentation] - if: ${{ always() && needs.pack.result == 'success' && needs.validate-release.result == 'success' && (needs.publish-documentation.result == 'success' || needs.publish-documentation.result == 'skipped') }} + needs: [pack, validate-release, publish-documentation, update-api-unshipped, promote-api-files] + if: | + always() && + needs.pack.result == 'success' && + needs.validate-release.result == 'success' && + (needs.publish-documentation.result == 'success' || needs.publish-documentation.result == 'skipped') && + (needs.promote-api-files.result == 'success' || needs.promote-api-files.result == 'skipped') && + (needs.update-api-unshipped.result == 'success' || needs.update-api-unshipped.result == 'skipped') env: package-artifact-name: ${{ needs.pack.outputs.package-artifact-name }} runs-on: ubuntu-latest @@ -272,9 +396,68 @@ jobs: is-preview: ${{ env.is-preview }} notes-start-tag: ${{ steps.determine-notes-start-tag.outputs.notes-start-tag }} + update-changelog: + name: 'Update CHANGELOG.md' + needs: [workflow-variables, release, versioning] + if: ${{ needs.workflow-variables.outputs.is-release == 'true' }} + runs-on: ubuntu-latest + env: + GH_TOKEN: ${{ github.token }} + release-version: ${{ needs.versioning.outputs.release-version }} + steps: + - name: 'Checkout ${{ github.ref }}' + uses: actions/checkout@v6 + with: + ref: ${{ github.ref }} + + - name: 'Fetch release notes' + shell: bash + run: | + gh release view ${{ env.release-version }} --json body --jq '.body' > /tmp/release-notes.txt + + - name: 'Prepend entry to CHANGELOG.md' + shell: bash + run: | + release_date=$(date -u +%Y-%m-%d) + { + echo "## ${{ env.release-version }} — ${release_date}" + echo "" + cat /tmp/release-notes.txt + echo "" + } > /tmp/new-entry.txt + awk ' + // { + print + print "" + while ((getline line < "/tmp/new-entry.txt") > 0) print line + close("/tmp/new-entry.txt") + next + } + { print } + ' CHANGELOG.md > /tmp/changelog-new.md + mv /tmp/changelog-new.md CHANGELOG.md + + - name: 'Configure git identity' + uses: './.github/actions/git/configure-identity' + + - name: 'Commit and push CHANGELOG.md' + shell: bash + run: | + git add CHANGELOG.md + git diff --staged --quiet || ( + git commit -m "Update CHANGELOG.md for ${{ env.release-version }}" && + git pull --rebase origin ${{ github.ref_name }} && + git push + ) + + - name: 'Write changelog summary' + shell: bash + run: | + echo "✅ CHANGELOG.md updated for **${{ env.release-version }}**." >> $GITHUB_STEP_SUMMARY + merge-to-main: name: 'Merge ${{ github.ref_name }} into main' - needs: [workflow-variables, release, versioning] + needs: [workflow-variables, release, versioning, update-changelog] if: ${{ needs.workflow-variables.outputs.is-release == 'true' }} runs-on: ubuntu-latest permissions: @@ -371,17 +554,10 @@ jobs: git checkout -b "${{ steps.resolve-support-branch.outputs.support-branch }}" git push --set-upstream origin "${{ steps.resolve-support-branch.outputs.support-branch }}" - - name: 'Lock support branch' - if: ${{ steps.check-support-branch.outputs.support-branch-exists == 'false' }} - uses: './.github/actions/github/branch-protection/lock' - with: - branch: ${{ steps.resolve-support-branch.outputs.support-branch }} - token: ${{ secrets.GH_ADMIN_TOKEN }} - - name: 'Write support branch summary' run: | if [[ "${{ steps.check-support-branch.outputs.support-branch-exists }}" == "false" ]]; then - echo "✅ Created and locked support branch **${{ steps.resolve-support-branch.outputs.support-branch }}**." >> $GITHUB_STEP_SUMMARY + echo "✅ Created support branch **${{ steps.resolve-support-branch.outputs.support-branch }}**." >> $GITHUB_STEP_SUMMARY else echo "⏭️ Support branch **${{ steps.resolve-support-branch.outputs.support-branch }}** already exists." >> $GITHUB_STEP_SUMMARY fi diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index cb8bb32a..00000000 --- a/AGENTS.md +++ /dev/null @@ -1,93 +0,0 @@ -# Polyline Algorithm Agents Instructions - -## Purpose - -Instructions for automated agents (bots, CI, and code review tools) and contributors interacting with the Polyline Algorithm library. - ---- - -## General Guidelines - -- All contributions and automation **must adhere to code style** (`.editorconfig`, `dotnet format`). -- **Unit tests** are required for new features and bug fixes (`tests/` directory). -- **Benchmarks** must be updated for performance-impacting changes (`benchmarks/` directory). - ---- - -## Pull Requests - -Agents and contributors should: - -- **Attach benchmark results** for encoding/decoding performance changes -- Document **public API changes** in XML comments and verify updates at [API Reference](https://petesramek.github.io/polyline-algorithm-csharp/) -- Run format and static analysis tools before submitting (`dotnet format`, analyzers) -- Update **README.md** and `/samples` for public API changes - ---- - -## Error Handling and Logging - -- Throw **descriptive exceptions** for invalid input/edge cases -- Use internal logging helpers for operational status (`LogInfoExtensions`, `LogWarningExtensions`) - ---- - -## Encoding/Decoding Agents - -- Use abstraction interfaces (`IPolylineEncoder`, `IPolylineDecoder` if available) -- Prefer extension methods for collections and arrays -- Validate latitude/longitude ranges - ---- - -## Issue and PR Templates - -Agents should reference standardized templates from `.github`. Contributors must use them for new issues or PRs. - ---- - -## Extensibility - -- Add encoding schemes or coordinate types in **separate classes/files** -- Register via factory pattern if supporting multiple algorithms -- Do not mix logic between different polyline versions - ---- - -## Future-proofing - -- Support for precision or custom coordinate fields: update `PolylineEncodingOptions` with clear doc comments - ---- - -## Documentation - -- Keep XML doc comments up-to-date in source files -- API reference is auto-generated and hosted at - [https://petesramek.github.io/polyline-algorithm-csharp/](https://petesramek.github.io/polyline-algorithm-csharp/) -- After public API changes, verify docs render correctly on the website -- Add usage samples in XML comments and `/samples` directory - ---- - -## Agent File Format (for `.github/agents`) - -Each agent instruction file should specify: - -``` -# AGENT INSTRUCTIONS - -- Purpose and scope -- Required tools/commands -- Coding and testing requirements -- Logging/error handling expectations -- Documentation or samples to update -``` - ---- - -## Contact & Questions - -Questions or clarifications: open a GitHub issue and tag `@petesramek`. - ---- diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..9264cdaa --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,10 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and release notes are generated automatically from merged pull requests. + +See all releases at: + + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..d0b9d1d8 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,47 @@ +# Contributor Covenant Code of Conduct + +## Our Commitment + +We are committed to providing a welcoming and inspiring community for all. We pledge to create an environment in which every individual feels valued, respected, and free from harassment and discrimination. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +- Using welcoming and inclusive language +- Being respectful of differing opinions, viewpoints, and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery and unwelcome sexual attention or advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement + +Community leaders are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Reporting + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainer responsible for enforcement. All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/Directory.Build.props b/Directory.Build.props index 96ebb124..80c3886e 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -6,6 +6,8 @@ enable true en + true + embedded @@ -20,6 +22,7 @@ + diff --git a/PolylineAlgorithm.slnx b/PolylineAlgorithm.slnx index 29fa9445..3c54b2a7 100644 --- a/PolylineAlgorithm.slnx +++ b/PolylineAlgorithm.slnx @@ -7,6 +7,7 @@ + diff --git a/README.md b/README.md index 9dfb8a18..0555c16f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # PolylineAlgorithm for .NET -Lightweight .NET Standard 2.1 library implementing Google-compliant Encoded Polyline Algorithm with strong input validation, modern API patterns, and extensibility for custom coordinate types. +[![NuGet](https://img.shields.io/nuget/v/PolylineAlgorithm)](https://www.nuget.org/packages/PolylineAlgorithm) +[![Build](https://github.com/petesramek/polyline-algorithm-csharp/actions/workflows/build.yml/badge.svg)](https://github.com/petesramek/polyline-algorithm-csharp/actions/workflows/build.yml) +[![License: MIT](https://img.shields.io/github/license/petesramek/polyline-algorithm-csharp)](./LICENSE) + +Google's Encoded Polyline Algorithm compresses sequences of geographic coordinates into a compact ASCII string, widely used in mapping APIs. This library provides a fully compliant .NET implementation with extensible, type-safe encoding and decoding APIs. ## Table of Contents @@ -17,15 +21,16 @@ Lightweight .NET Standard 2.1 library implementing Google-compliant Encoded Poly ## Features - Fully compliant Google Encoded Polyline Algorithm for .NET Standard 2.1+ -- Extensible encoding and decoding APIs for custom coordinate and polyline types (`IPolylineEncoder`, `IPolylineDecoder`, `AbstractPolylineEncoder`, `AbstractPolylineDecoder`) -- Extension methods for encoding from `List` and arrays (`PolylineEncoderExtensions`) -- Robust input validation with descriptive exceptions for malformed/invalid data +- Extensible APIs — implement your own encoder/decoder for any coordinate or polyline type +- Robust input validation with descriptive exceptions for malformed or out-of-range data - Advanced configuration via `PolylineEncodingOptions` (precision, buffer size, logging) -- Logging and diagnostic support for CI/CD and developer diagnostics via `Microsoft.Extensions.Logging` -- Low-level utilities for normalization, validation, encoding and decoding via static `PolylineEncoding` class +- Extension methods for encoding directly from `List` and arrays +- Logging and diagnostic support via `Microsoft.Extensions.Logging` +- Low-level utilities for normalization, validation, and bit-level operations via static `PolylineEncoding` class +- Thread-safe, stateless APIs - Thorough unit tests and benchmarks for correctness and performance - Auto-generated API documentation ([API Reference](https://petesramek.github.io/polyline-algorithm-csharp/)) -- Support for .NET Core, .NET 5+, Xamarin, Unity, Blazor, and other platforms supporting `netstandard2.1` +- Supports .NET Core, .NET 5+, Xamarin, Unity, Blazor, and any platform targeting `netstandard2.1` ## Installation @@ -43,7 +48,19 @@ Install-Package PolylineAlgorithm ## Usage -The library provides abstract base classes to implement your own encoder and decoder for any coordinate and polyline type. +The library provides abstract base classes to implement your own encoder and decoder for any coordinate and polyline type. Inherit from `AbstractPolylineEncoder` or `AbstractPolylineDecoder`, override the coordinate accessors, then call `Encode` or `Decode`. + +### Quick Start + +```csharp +// 1. Implement a minimal encoder (see full example below) +var encoder = new MyPolylineEncoder(); +string encoded = encoder.Encode(coordinates); // e.g. "yseiHoc_MwacOjnwM" + +// 2. Implement a minimal decoder (see full example below) +var decoder = new MyPolylineDecoder(); +IEnumerable<(double Latitude, double Longitude)> decoded = decoder.Decode(encoded); +``` ### Custom encoder and decoder @@ -56,23 +73,9 @@ using PolylineAlgorithm; using PolylineAlgorithm.Abstraction; public sealed class MyPolylineEncoder : AbstractPolylineEncoder<(double Latitude, double Longitude), string> { - public MyPolylineEncoder() - : base() { } - - public MyPolylineEncoder(PolylineEncodingOptions options) - : base(options) { } - - protected override double GetLatitude((double Latitude, double Longitude) coordinate) { - return coordinate.Latitude; - } - - protected override double GetLongitude((double Latitude, double Longitude) coordinate) { - return coordinate.Longitude; - } - - protected override string CreatePolyline(ReadOnlyMemory polyline) { - return polyline.ToString(); - } + protected override double GetLatitude((double Latitude, double Longitude) coordinate) => coordinate.Latitude; + protected override double GetLongitude((double Latitude, double Longitude) coordinate) => coordinate.Longitude; + protected override string CreatePolyline(ReadOnlyMemory polyline) => polyline.ToString(); } ``` @@ -102,19 +105,8 @@ using PolylineAlgorithm; using PolylineAlgorithm.Abstraction; public sealed class MyPolylineDecoder : AbstractPolylineDecoder { - public MyPolylineDecoder() - : base() { } - - public MyPolylineDecoder(PolylineEncodingOptions options) - : base(options) { } - - protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude) { - return (latitude, longitude); - } - - protected override ReadOnlyMemory GetReadOnlyMemory(in string polyline) { - return polyline.AsMemory(); - } + protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude) => (latitude, longitude); + protected override ReadOnlyMemory GetReadOnlyMemory(in string polyline) => polyline.AsMemory(); } ``` @@ -136,8 +128,13 @@ Full API docs and guides (auto-generated from source) are available at [API Refe ## Benchmarks -- See `/benchmarks` in the repo for performance evaluation. -- Contributors: Update benchmarks and document results for performance-impacting PRs. +- See [`/benchmarks`](./benchmarks) in the repo for benchmark projects. +- Run benchmarks with: + ```shell + dotnet run --project benchmarks/PolylineAlgorithm.Benchmarks --configuration Release + ``` +- For guidance on writing and interpreting benchmarks, see [docs/benchmarks.md](./docs/benchmarks.md). +- Contributors: update benchmarks and document results for performance-impacting PRs. ## FAQ @@ -173,13 +170,13 @@ A: Currently, only batch encode/decode is supported. For streaming scenarios, im ## Contributing -- Follow code style and PR instructions in [AGENTS.md](./AGENTS.md). +- Follow code style and PR instructions in [CONTRIBUTING.md](./CONTRIBUTING.md). - Ensure all features are covered by tests and XML doc comments. - For questions or suggestions, open an issue and use the provided templates. ## Support -Have a question, bug, or feature request? [Open an issue!](https://github.com/petesramek/polyline-algorithm-csharp/issues) +Have a question, bug, or feature request? [Open an issue](https://github.com/petesramek/polyline-algorithm-csharp/issues/new/choose) — bug report and feature request templates are available to guide you. --- diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..8ca1471a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,23 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +| ------- | --------- | +| Latest | ✅ | +| Older | ❌ | + +Only the latest published version receives security fixes. If you are on an older version, please upgrade. + +## Reporting a Vulnerability + +**Please do not open a public GitHub issue for security vulnerabilities.** + +Report security issues privately via [GitHub Security Advisories](https://github.com/petesramek/polyline-algorithm-csharp/security/advisories/new). + +Include: +- A description of the vulnerability +- Steps to reproduce or a proof-of-concept +- Potential impact assessment + +You can expect an initial response within 5 business days. Once confirmed, a fix will be prioritized and a patch release issued. You will be credited in the release notes unless you prefer to remain anonymous. diff --git a/api-reference/1.0/PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.yml b/api-reference/1.0/PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.yml deleted file mode 100644 index 6349f59c..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.yml +++ /dev/null @@ -1,233 +0,0 @@ -### YamlMime:ApiPage -title: Class AbstractPolylineDecoder -body: -- api1: Class AbstractPolylineDecoder - id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2 - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/1.0/PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.yml b/api-reference/1.0/PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.yml deleted file mode 100644 index ec0a65e9..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.yml +++ /dev/null @@ -1,219 +0,0 @@ -### YamlMime:ApiPage -title: Class AbstractPolylineEncoder -body: -- api1: Class AbstractPolylineEncoder - id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2 - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/1.0/PolylineAlgorithm.Abstraction.IPolylineDecoder-2.yml b/api-reference/1.0/PolylineAlgorithm.Abstraction.IPolylineDecoder-2.yml deleted file mode 100644 index 704f92b2..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Abstraction.IPolylineDecoder-2.yml +++ /dev/null @@ -1,90 +0,0 @@ -### YamlMime:ApiPage -title: Interface IPolylineDecoder -body: -- api1: Interface IPolylineDecoder - id: PolylineAlgorithm_Abstraction_IPolylineDecoder_2 - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/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/1.0/PolylineAlgorithm.Abstraction.IPolylineEncoder-2.yml b/api-reference/1.0/PolylineAlgorithm.Abstraction.IPolylineEncoder-2.yml deleted file mode 100644 index 979fe774..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Abstraction.IPolylineEncoder-2.yml +++ /dev/null @@ -1,142 +0,0 @@ -### YamlMime:ApiPage -title: Interface IPolylineEncoder -body: -- api1: Interface IPolylineEncoder - id: PolylineAlgorithm_Abstraction_IPolylineEncoder_2 - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/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/1.0/PolylineAlgorithm.Abstraction.yml b/api-reference/1.0/PolylineAlgorithm.Abstraction.yml deleted file mode 100644 index e9de48f7..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Abstraction.yml +++ /dev/null @@ -1,34 +0,0 @@ -### 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/1.0/PolylineAlgorithm.Extensions.PolylineDecoderExtensions.yml b/api-reference/1.0/PolylineAlgorithm.Extensions.PolylineDecoderExtensions.yml deleted file mode 100644 index 4b97f584..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Extensions.PolylineDecoderExtensions.yml +++ /dev/null @@ -1,195 +0,0 @@ -### YamlMime:ApiPage -title: Class PolylineDecoderExtensions -body: -- api1: Class PolylineDecoderExtensions - id: PolylineAlgorithm_Extensions_PolylineDecoderExtensions - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/1.0/PolylineAlgorithm.Extensions.PolylineEncoderExtensions.yml b/api-reference/1.0/PolylineAlgorithm.Extensions.PolylineEncoderExtensions.yml deleted file mode 100644 index aeba23f9..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Extensions.PolylineEncoderExtensions.yml +++ /dev/null @@ -1,139 +0,0 @@ -### YamlMime:ApiPage -title: Class PolylineEncoderExtensions -body: -- api1: Class PolylineEncoderExtensions - id: PolylineAlgorithm_Extensions_PolylineEncoderExtensions - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/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/develop/1.0/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/1.0/PolylineAlgorithm.Extensions.yml b/api-reference/1.0/PolylineAlgorithm.Extensions.yml deleted file mode 100644 index c39da0ca..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Extensions.yml +++ /dev/null @@ -1,19 +0,0 @@ -### 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/1.0/PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.yml b/api-reference/1.0/PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.yml deleted file mode 100644 index 45962074..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.yml +++ /dev/null @@ -1,313 +0,0 @@ -### YamlMime:ApiPage -title: Class ExceptionGuard -body: -- api1: Class ExceptionGuard - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L29 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard - commentId: T:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard -- facts: - - name: Namespace - value: - text: PolylineAlgorithm.Internal.Diagnostics - url: PolylineAlgorithm.Internal.Diagnostics.html - - name: Assembly - value: PolylineAlgorithm.dll -- markdown: Centralizes exception throwing for common validation and error scenarios used across the library. -- code: public static class ExceptionGuard -- h4: Inheritance -- inheritance: - - text: object - url: https://learn.microsoft.com/dotnet/api/system.object - - text: ExceptionGuard - url: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.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: >- - Methods in this class are intentionally small and annotated so that they can act as single - - call sites for throwing exceptions (improving inlining and stack traces). Many members have - - attributes to avoid polluting callers' stack traces (__StackTraceHidden__ on supported targets) - - or to prevent inlining on older targets. -- h2: Methods -- api3: StackAllocLimitMustBeEqualOrGreaterThan(int, string) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_StackAllocLimitMustBeEqualOrGreaterThan_System_Int32_System_String_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L97 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.StackAllocLimitMustBeEqualOrGreaterThan(System.Int32,System.String) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.StackAllocLimitMustBeEqualOrGreaterThan(System.Int32,System.String) -- markdown: Throws an when a stack allocation limit is below the required minimum. -- code: >- - [DoesNotReturn] - - public static void StackAllocLimitMustBeEqualOrGreaterThan(int minValue, string paramName) -- h4: Parameters -- parameters: - - name: minValue - type: - - text: int - url: https://learn.microsoft.com/dotnet/api/system.int32 - description: Minimum required stack allocation limit. - - name: paramName - type: - - text: string - url: https://learn.microsoft.com/dotnet/api/system.string - description: Name of the parameter representing the limit. -- api3: ThrowArgumentCannotBeEmptyEnumerationMessage(string) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowArgumentCannotBeEmptyEnumerationMessage_System_String_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L111 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowArgumentCannotBeEmptyEnumerationMessage(System.String) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowArgumentCannotBeEmptyEnumerationMessage(System.String) -- markdown: Throws an when an enumeration argument is empty but must contain at least one element. -- code: >- - [DoesNotReturn] - - public static void ThrowArgumentCannotBeEmptyEnumerationMessage(string paramName) -- h4: Parameters -- parameters: - - name: paramName - type: - - text: string - url: https://learn.microsoft.com/dotnet/api/system.string - description: Name of the parameter representing the enumeration. -- api3: ThrowArgumentNull(string) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowArgumentNull_System_String_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L51 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowArgumentNull(System.String) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowArgumentNull(System.String) -- markdown: Throws an for a null argument. -- code: >- - [DoesNotReturn] - - public static void ThrowArgumentNull(string paramName) -- h4: Parameters -- parameters: - - name: paramName - type: - - text: string - url: https://learn.microsoft.com/dotnet/api/system.string - description: Name of the parameter that was null. -- api3: ThrowBufferOverflow(string) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowBufferOverflow_System_String_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L65 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowBufferOverflow(System.String) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowBufferOverflow(System.String) -- markdown: Throws an with a provided message. -- code: >- - [DoesNotReturn] - - public static void ThrowBufferOverflow(string message) -- h4: Parameters -- parameters: - - name: message - type: - - text: string - url: https://learn.microsoft.com/dotnet/api/system.string - description: Message that describes the overflow condition. -- api3: ThrowCoordinateValueOutOfRange(double, double, double, string) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowCoordinateValueOutOfRange_System_Double_System_Double_System_Double_System_String_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L82 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowCoordinateValueOutOfRange(System.Double,System.Double,System.Double,System.String) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowCoordinateValueOutOfRange(System.Double,System.Double,System.Double,System.String) -- markdown: Throws an when a coordinate value is outside the allowed range. -- code: >- - [DoesNotReturn] - - public static void ThrowCoordinateValueOutOfRange(double value, double min, double max, string paramName) -- h4: Parameters -- parameters: - - name: value - type: - - text: double - url: https://learn.microsoft.com/dotnet/api/system.double - description: The coordinate value that was out of range. - - name: min - type: - - text: double - url: https://learn.microsoft.com/dotnet/api/system.double - description: Inclusive minimum allowed value. - - name: max - type: - - text: double - url: https://learn.microsoft.com/dotnet/api/system.double - description: Inclusive maximum allowed value. - - name: paramName - type: - - text: string - url: https://learn.microsoft.com/dotnet/api/system.string - description: Name of the parameter containing the coordinate. -- api3: ThrowCouldNotWriteEncodedValueToBuffer() - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowCouldNotWriteEncodedValueToBuffer - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L124 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowCouldNotWriteEncodedValueToBuffer - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowCouldNotWriteEncodedValueToBuffer -- markdown: Throws an when an encoded value could not be written to the destination buffer. -- code: >- - [DoesNotReturn] - - public static void ThrowCouldNotWriteEncodedValueToBuffer() -- api3: ThrowDestinationArrayLengthMustBeEqualOrGreaterThanPolylineLength(int, int, string) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowDestinationArrayLengthMustBeEqualOrGreaterThanPolylineLength_System_Int32_System_Int32_System_String_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L140 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowDestinationArrayLengthMustBeEqualOrGreaterThanPolylineLength(System.Int32,System.Int32,System.String) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowDestinationArrayLengthMustBeEqualOrGreaterThanPolylineLength(System.Int32,System.Int32,System.String) -- markdown: Throws an when a destination array is not large enough to contain the polyline data. -- code: >- - [DoesNotReturn] - - public static void ThrowDestinationArrayLengthMustBeEqualOrGreaterThanPolylineLength(int destinationLength, int polylineLength, string paramName) -- h4: Parameters -- parameters: - - name: destinationLength - type: - - text: int - url: https://learn.microsoft.com/dotnet/api/system.int32 - description: The length of the destination array. - - name: polylineLength - type: - - text: int - url: https://learn.microsoft.com/dotnet/api/system.int32 - description: The required polyline length. - - name: paramName - type: - - text: string - url: https://learn.microsoft.com/dotnet/api/system.string - description: Name of the parameter representing the destination array. -- api3: ThrowInvalidPolylineBlockTerminator() - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowInvalidPolylineBlockTerminator - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L212 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowInvalidPolylineBlockTerminator - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowInvalidPolylineBlockTerminator -- markdown: Throws an when the polyline block terminator is invalid. -- code: >- - [DoesNotReturn] - - public static void ThrowInvalidPolylineBlockTerminator() -- api3: ThrowInvalidPolylineCharacter(char, int) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowInvalidPolylineCharacter_System_Char_System_Int32_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L171 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowInvalidPolylineCharacter(System.Char,System.Int32) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowInvalidPolylineCharacter(System.Char,System.Int32) -- markdown: Throws an when an unexpected character is encountered in the polyline. -- code: >- - [DoesNotReturn] - - public static void ThrowInvalidPolylineCharacter(char character, int position) -- h4: Parameters -- parameters: - - name: character - type: - - text: char - url: https://learn.microsoft.com/dotnet/api/system.char - description: The invalid character. - - name: position - type: - - text: int - url: https://learn.microsoft.com/dotnet/api/system.int32 - description: Position in the polyline where the character was found. -- api3: ThrowInvalidPolylineFormat(long) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowInvalidPolylineFormat_System_Int64_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L199 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowInvalidPolylineFormat(System.Int64) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowInvalidPolylineFormat(System.Int64) -- markdown: Throws an when the polyline format is malformed. -- code: >- - [DoesNotReturn] - - public static void ThrowInvalidPolylineFormat(long position) -- h4: Parameters -- parameters: - - name: position - type: - - text: long - url: https://learn.microsoft.com/dotnet/api/system.int64 - description: Approximate position where the polyline became malformed. -- api3: ThrowInvalidPolylineLength(int, int) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowInvalidPolylineLength_System_Int32_System_Int32_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L156 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowInvalidPolylineLength(System.Int32,System.Int32) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowInvalidPolylineLength(System.Int32,System.Int32) -- markdown: Throws an when the polyline length is invalid. -- code: >- - [DoesNotReturn] - - public static void ThrowInvalidPolylineLength(int length, int min) -- h4: Parameters -- parameters: - - name: length - type: - - text: int - url: https://learn.microsoft.com/dotnet/api/system.int32 - description: The invalid length. - - name: min - type: - - text: int - url: https://learn.microsoft.com/dotnet/api/system.int32 - description: The minimum required length. -- api3: ThrowNotFiniteNumber(string) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowNotFiniteNumber_System_String_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L37 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowNotFiniteNumber(System.String) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowNotFiniteNumber(System.String) -- markdown: Throws an when a numeric argument is not a finite value. -- code: >- - [DoesNotReturn] - - public static void ThrowNotFiniteNumber(string paramName) -- h4: Parameters -- parameters: - - name: paramName - type: - - text: string - url: https://learn.microsoft.com/dotnet/api/system.string - description: Name of the parameter that had a non-finite value. -- api3: ThrowPolylineBlockTooLong(int) - id: PolylineAlgorithm_Internal_Diagnostics_ExceptionGuard_ThrowPolylineBlockTooLong_System_Int32_ - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Internal/Diagnostics/ExceptionGuard.cs#L185 - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowPolylineBlockTooLong(System.Int32) - commentId: M:PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.ThrowPolylineBlockTooLong(System.Int32) -- markdown: Throws an when a polyline block is longer than allowed. -- code: >- - [DoesNotReturn] - - public static void ThrowPolylineBlockTooLong(int position) -- h4: Parameters -- parameters: - - name: position - type: - - text: int - url: https://learn.microsoft.com/dotnet/api/system.int32 - description: Position in the polyline where the block exceeded the allowed length. -languageId: csharp -metadata: - description: Centralizes exception throwing for common validation and error scenarios used across the library. diff --git a/api-reference/1.0/PolylineAlgorithm.Internal.Diagnostics.yml b/api-reference/1.0/PolylineAlgorithm.Internal.Diagnostics.yml deleted file mode 100644 index dabb499a..00000000 --- a/api-reference/1.0/PolylineAlgorithm.Internal.Diagnostics.yml +++ /dev/null @@ -1,15 +0,0 @@ -### YamlMime:ApiPage -title: Namespace PolylineAlgorithm.Internal.Diagnostics -body: -- api1: Namespace PolylineAlgorithm.Internal.Diagnostics - id: PolylineAlgorithm_Internal_Diagnostics - metadata: - uid: PolylineAlgorithm.Internal.Diagnostics - commentId: N:PolylineAlgorithm.Internal.Diagnostics -- h3: Classes -- parameters: - - type: - text: ExceptionGuard - url: PolylineAlgorithm.Internal.Diagnostics.ExceptionGuard.html - description: Centralizes exception throwing for common validation and error scenarios used across the library. -languageId: csharp diff --git a/api-reference/1.0/PolylineAlgorithm.InvalidPolylineException.yml b/api-reference/1.0/PolylineAlgorithm.InvalidPolylineException.yml deleted file mode 100644 index b776c617..00000000 --- a/api-reference/1.0/PolylineAlgorithm.InvalidPolylineException.yml +++ /dev/null @@ -1,102 +0,0 @@ -### YamlMime:ApiPage -title: Class InvalidPolylineException -body: -- api1: Class InvalidPolylineException - id: PolylineAlgorithm_InvalidPolylineException - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/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/develop/1.0/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/1.0/PolylineAlgorithm.PolylineEncoding.yml b/api-reference/1.0/PolylineAlgorithm.PolylineEncoding.yml deleted file mode 100644 index 127dbf53..00000000 --- a/api-reference/1.0/PolylineAlgorithm.PolylineEncoding.yml +++ /dev/null @@ -1,529 +0,0 @@ -### YamlMime:ApiPage -title: Class PolylineEncoding -body: -- api1: Class PolylineEncoding - id: PolylineAlgorithm_PolylineEncoding - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/src/PolylineAlgorithm/PolylineEncoding.cs#L121 - 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/develop/1.0/src/PolylineAlgorithm/PolylineEncoding.cs#L297 - 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/develop/1.0/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/develop/1.0/src/PolylineAlgorithm/PolylineEncoding.cs#L168 - 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/develop/1.0/src/PolylineAlgorithm/PolylineEncoding.cs#L236 - 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/develop/1.0/src/PolylineAlgorithm/PolylineEncoding.cs#L437 - 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/develop/1.0/src/PolylineAlgorithm/PolylineEncoding.cs#L391 - 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/develop/1.0/src/PolylineAlgorithm/PolylineEncoding.cs#L369 - 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/1.0/PolylineAlgorithm.PolylineEncodingOptions.yml b/api-reference/1.0/PolylineAlgorithm.PolylineEncodingOptions.yml deleted file mode 100644 index 2e3880ce..00000000 --- a/api-reference/1.0/PolylineAlgorithm.PolylineEncodingOptions.yml +++ /dev/null @@ -1,127 +0,0 @@ -### YamlMime:ApiPage -title: Class PolylineEncodingOptions -body: -- api1: Class PolylineEncodingOptions - id: PolylineAlgorithm_PolylineEncodingOptions - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/1.0/PolylineAlgorithm.PolylineEncodingOptionsBuilder.yml b/api-reference/1.0/PolylineAlgorithm.PolylineEncodingOptionsBuilder.yml deleted file mode 100644 index 92e6d942..00000000 --- a/api-reference/1.0/PolylineAlgorithm.PolylineEncodingOptionsBuilder.yml +++ /dev/null @@ -1,141 +0,0 @@ -### YamlMime:ApiPage -title: Class PolylineEncodingOptionsBuilder -body: -- api1: Class PolylineEncodingOptionsBuilder - id: PolylineAlgorithm_PolylineEncodingOptionsBuilder - src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/develop/1.0/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/1.0/PolylineAlgorithm.yml b/api-reference/1.0/PolylineAlgorithm.yml deleted file mode 100644 index b60dc3c0..00000000 --- a/api-reference/1.0/PolylineAlgorithm.yml +++ /dev/null @@ -1,38 +0,0 @@ -### 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/1.0/toc.yml b/api-reference/1.0/toc.yml deleted file mode 100644 index d1ffc58a..00000000 --- a/api-reference/1.0/toc.yml +++ /dev/null @@ -1,34 +0,0 @@ -### 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/api-reference/guide/benchmarks.md b/api-reference/guide/benchmarks.md new file mode 100644 index 00000000..47b453f9 --- /dev/null +++ b/api-reference/guide/benchmarks.md @@ -0,0 +1,11 @@ +--- +title: Benchmarks +--- +# Benchmarks + +Performance benchmarks for **PolylineAlgorithm for .NET** measured using [BenchmarkDotNet](https://benchmarkdotnet.org/). + +> [!NOTE] +> Benchmarks are generated automatically during the release process. Results may vary depending on hardware and runtime version. + +{benchmarks_section} diff --git a/api-reference/guide/toc.yml b/api-reference/guide/toc.yml index 015a9943..e9d9e716 100644 --- a/api-reference/guide/toc.yml +++ b/api-reference/guide/toc.yml @@ -8,3 +8,5 @@ href: sample.md - name: FAQ href: faq.md +- name: Benchmarks + href: benchmarks.md diff --git a/benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncodingBenchmark.cs b/benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncodingBenchmark.cs index 861ad85f..ee716fca 100644 --- a/benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncodingBenchmark.cs +++ b/benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncodingBenchmark.cs @@ -28,11 +28,5 @@ public void Setup() { } [Benchmark(Baseline = true)] - public void ValidateCharRange() => PolylineEncoding.ValidateCharRange(polyline); - - [Benchmark] - public void ValidateBlockLength() => PolylineEncoding.ValidateBlockLength(polyline); - - [Benchmark] public void ValidateFormat() => PolylineEncoding.ValidateFormat(polyline); } \ No newline at end of file diff --git a/docs/local-development.md b/docs/local-development.md index 48fa5f76..ab2da8ab 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -72,3 +72,24 @@ The CI `format` job also runs `dotnet format` automatically on every push to non ## Editor Configuration Code style rules are stored in `.editorconfig` at the repository root. Any compliant IDE (Visual Studio, VS Code with C# Dev Kit, Rider) will pick these up automatically. + +## Required Repository Secrets and Variables + +The CI/CD workflows rely on the following GitHub repository secrets and variables. + +### Secrets + +| Name | Description | +|------|-------------| +| `NUGET_PACKAGE_FEED_API_KEY` | API key for the Azure Artifacts NuGet feed | + +### Variables + +| Name | Description | +|------|-------------| +| `NUGET_PACKAGE_FEED_URL` | NuGet feed URL | +| `BENCHMARKDOTNET_RUN_OVERRIDE` | Set to `true` to force benchmarks to run on non-release PRs | +| `BENCHMARKDOTNET_RUNTIMES` | Runtimes to benchmark (e.g. `net8.0 net10.0`) | +| `BENCHMARKDOTNET_FILTER` | Benchmark filter pattern (e.g. `*`) | +| `DEFAULT_BUILD_FRAMEWORK` | Default target framework for builds (e.g. `net10.0`) | +| `SRC_DEFAULT_GLOB_PATTERN` | Glob pattern for source project files (e.g. `**/PolylineAlgorithm.csproj`) | diff --git a/docs/workflows.md b/docs/workflows.md index 4c864783..8782270f 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -87,6 +87,7 @@ Version bumping runs independently via `bump-version.yml` (manual trigger). | `pack` | `versioning`, `build` | Packages binaries | | `publish-package` | `pack` | Publishes to NuGet.org (Production environment) | | `create-release` | `versioning`, `publish-package` | Creates a git tag + GitHub release with auto-generated notes | +| `update-changelog` | `release` | Fetches release notes and prepends a new entry to `CHANGELOG.md` — stable releases only | | `generate-docs` | `versioning` | Builds DocFX site | | `publish-docs` | `generate-docs` | Deploys to GitHub Pages | diff --git a/samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs b/samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs index 82899203..d7dcb13e 100644 --- a/samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs +++ b/samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineDecoder.cs @@ -12,7 +12,7 @@ namespace PolylineAlgorithm.NetTopologySuite.Sample; /// /// Polyline decoder using NetTopologySuite. /// -public sealed class NetTopologyPolylineDecoder : AbstractPolylineDecoder { +internal sealed class NetTopologyPolylineDecoder : AbstractPolylineDecoder { /// /// Creates a NetTopologySuite point from latitude and longitude. /// diff --git a/samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs b/samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs index 649547bd..c6719000 100644 --- a/samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs +++ b/samples/PolylineAlgorithm.NetTopologySuite.Sample/NetTopologyPolylineEncoder.cs @@ -11,7 +11,7 @@ namespace PolylineAlgorithm.NetTopologySuite.Sample; /// /// Polyline encoder using NetTopologySuite's Point type. /// -public sealed class NetTopologyPolylineEncoder : AbstractPolylineEncoder { +internal sealed class NetTopologyPolylineEncoder : AbstractPolylineEncoder { /// /// Creates encoded polyline string from memory. /// @@ -31,9 +31,7 @@ protected override string CreatePolyline(ReadOnlyMemory polyline) { /// Point instance. /// Latitude value. protected override double GetLatitude(Point current) { - if (current is null) { - throw new ArgumentNullException(nameof(current)); - } + ArgumentNullException.ThrowIfNull(current); // NetTopologySuite Point: Y = latitude return current.Y; @@ -45,9 +43,7 @@ protected override double GetLatitude(Point current) { /// Point instance. /// Longitude value. protected override double GetLongitude(Point current) { - if (current is null) { - throw new ArgumentNullException(nameof(current)); - } + ArgumentNullException.ThrowIfNull(current); // NetTopologySuite Point: X = longitude return current.X; diff --git a/samples/PolylineAlgorithm.NetTopologySuite.Sample/PolylineAlgorithm.NetTopologySuite.Sample.csproj b/samples/PolylineAlgorithm.NetTopologySuite.Sample/PolylineAlgorithm.NetTopologySuite.Sample.csproj index 57d5f7c1..fef82026 100644 --- a/samples/PolylineAlgorithm.NetTopologySuite.Sample/PolylineAlgorithm.NetTopologySuite.Sample.csproj +++ b/samples/PolylineAlgorithm.NetTopologySuite.Sample/PolylineAlgorithm.NetTopologySuite.Sample.csproj @@ -1,7 +1,8 @@  - netstandard2.1 + Exe + net10.0 diff --git a/samples/PolylineAlgorithm.NetTopologySuite.Sample/Program.cs b/samples/PolylineAlgorithm.NetTopologySuite.Sample/Program.cs new file mode 100644 index 00000000..ca9a8a6f --- /dev/null +++ b/samples/PolylineAlgorithm.NetTopologySuite.Sample/Program.cs @@ -0,0 +1,46 @@ +// +// Copyright © Pete Sramek. All rights reserved. +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// + +using NetTopologySuite.Geometries; +using PolylineAlgorithm.NetTopologySuite.Sample; + +public class Program { + public static void Main(string[] args) { + // Sample route: Seattle → Bellevue → Redmond + var points = new Point[] + { + new(x: -122.3503, y: 47.6219), // Seattle (x = longitude, y = latitude) + new(x: -122.2015, y: 47.6101), // Bellevue + new(x: -122.1215, y: 47.6740), // Redmond + }; + + var encoder = new NetTopologyPolylineEncoder(); + var decoder = new NetTopologyPolylineDecoder(); + + // Encode + string encoded = encoder.Encode(points); + + Console.WriteLine("=== NetTopologySuite Polyline Sample ==="); + Console.WriteLine(); + Console.WriteLine("Input points (longitude, latitude):"); + + foreach (Point p in points) { + Console.WriteLine($" ({p.X}, {p.Y})"); + } + + Console.WriteLine(); + Console.WriteLine($"Encoded polyline: {encoded}"); + Console.WriteLine(); + + // Decode + IEnumerable decoded = decoder.Decode(encoded); + + Console.WriteLine("Decoded points (longitude, latitude):"); + + foreach (Point p in decoded) { + Console.WriteLine($" ({p.X}, {p.Y})"); + } + } +} \ No newline at end of file diff --git a/samples/PolylineAlgorithm.SensorData.Sample/PolylineAlgorithm.SensorData.Sample.csproj b/samples/PolylineAlgorithm.SensorData.Sample/PolylineAlgorithm.SensorData.Sample.csproj new file mode 100644 index 00000000..3e1bcb63 --- /dev/null +++ b/samples/PolylineAlgorithm.SensorData.Sample/PolylineAlgorithm.SensorData.Sample.csproj @@ -0,0 +1,16 @@ + + + + Exe + net10.0 + + + + false + + + + + + + diff --git a/samples/PolylineAlgorithm.SensorData.Sample/Program.cs b/samples/PolylineAlgorithm.SensorData.Sample/Program.cs new file mode 100644 index 00000000..e14977f9 --- /dev/null +++ b/samples/PolylineAlgorithm.SensorData.Sample/Program.cs @@ -0,0 +1,49 @@ +// +// Copyright © Pete Sramek. All rights reserved. +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// + +using PolylineAlgorithm.SensorData.Sample; + +public static class Program { + public static void Main(string[] args) { + // Sample temperature readings from a sensor over six seconds + var readings = new SensorReading[] + { + new(DateTimeOffset.UtcNow, 23.5), + new(DateTimeOffset.UtcNow.AddSeconds(1), 23.7), + new(DateTimeOffset.UtcNow.AddSeconds(2), 24.1), + new(DateTimeOffset.UtcNow.AddSeconds(3), 25.0), + new(DateTimeOffset.UtcNow.AddSeconds(4), 24.8), + new(DateTimeOffset.UtcNow.AddSeconds(5), 24.8), + new(DateTimeOffset.UtcNow.AddSeconds(6), 22.3), + }; + + var encoder = new SensorDataEncoder(); + var decoder = new SensorDataDecoder(); + + // Encode + string encoded = encoder.Encode(readings); + + Console.WriteLine("=== Sensor Data Polyline Sample ==="); + Console.WriteLine(); + Console.WriteLine("Input readings:"); + + foreach (SensorReading r in readings) { + Console.WriteLine($" [{r.Timestamp:HH:mm:ss}] {r.Temperature:F1} °C"); + } + + Console.WriteLine(); + Console.WriteLine($"Encoded polyline: {encoded}"); + Console.WriteLine(); + + // Decode (timestamps and temperatures are both recovered) + IEnumerable decoded = decoder.Decode(encoded); + + Console.WriteLine("Decoded readings:"); + + foreach (SensorReading r in decoded) { + Console.WriteLine($" [{r.Timestamp:HH:mm:ss}] {r.Temperature:F1} °C"); + } + } +} \ No newline at end of file diff --git a/samples/PolylineAlgorithm.SensorData.Sample/Properties/CodeCoverage.cs b/samples/PolylineAlgorithm.SensorData.Sample/Properties/CodeCoverage.cs new file mode 100644 index 00000000..e3468ef6 --- /dev/null +++ b/samples/PolylineAlgorithm.SensorData.Sample/Properties/CodeCoverage.cs @@ -0,0 +1,8 @@ +// +// Copyright © Pete Sramek. All rights reserved. +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// + +using System.Diagnostics.CodeAnalysis; + +[assembly: ExcludeFromCodeCoverage] diff --git a/samples/PolylineAlgorithm.SensorData.Sample/SensorDataDecoder.cs b/samples/PolylineAlgorithm.SensorData.Sample/SensorDataDecoder.cs new file mode 100644 index 00000000..9c63d647 --- /dev/null +++ b/samples/PolylineAlgorithm.SensorData.Sample/SensorDataDecoder.cs @@ -0,0 +1,107 @@ +// +// Copyright © Pete Sramek. All rights reserved. +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// + +namespace PolylineAlgorithm.SensorData.Sample; + +using PolylineAlgorithm.Abstraction; +using System.Collections.Generic; +using System.Threading; + +/// +/// Decodes a compact polyline string produced by back into a sequence +/// of values. +/// +/// +/// +/// This class demonstrates implementing for a custom +/// scalar type, following the same structural pattern as . +/// +/// +/// Each encoded pair consists of a delta-compressed Unix timestamp (seconds since Unix epoch, precision 0) +/// followed by a delta-compressed temperature value (at ). +/// Both are recovered and used to reconstruct the original . +/// +/// +[System.Diagnostics.CodeAnalysis.SuppressMessage("Sonar", "S4456:Parameter validation in yielding methods should be wrapped", Justification = "Inlined by design to demonstrate a simple iterator without a wrapper method.")] +internal sealed class SensorDataDecoder : IPolylineDecoder { + /// + /// Initializes a new instance of the class with default encoding options. + /// + public SensorDataDecoder() + : this(new PolylineEncodingOptions()) { } + + /// + /// Initializes a new instance of the class with the specified encoding options. + /// + /// + /// The to use for decoding operations. + /// The value must match the precision used during encoding. + /// + /// + /// Thrown when is . + /// + public SensorDataDecoder(PolylineEncodingOptions options) { + ArgumentNullException.ThrowIfNull(options); + + Options = options; + } + + /// + /// Gets the encoding options used by this decoder. + /// + public PolylineEncodingOptions Options { get; } + + /// + /// Decodes a polyline string back into a sequence of values. + /// + /// + /// The polyline-encoded string produced by . + /// + /// + /// A that can be used to cancel the decoding operation. + /// + /// + /// An of whose + /// and values + /// are recovered from the encoded string. + /// + /// + /// Thrown when is . + /// + /// + /// Thrown when is empty. + /// + /// + /// Thrown when requests cancellation. + /// + public IEnumerable Decode(string polyline, CancellationToken cancellationToken = default) { + ArgumentNullException.ThrowIfNull(polyline); + + if (polyline.Length < 1) { + throw new ArgumentException("Encoded polyline must not be empty.", nameof(polyline)); + } + + ReadOnlyMemory memory = polyline.AsMemory(); + int position = 0; + // Mirror the encoder's base epoch so the first delta decodes back to the correct Unix seconds. + int accumulatedTimestamp = SensorDataEncoder.TimestampBaseEpochSeconds; + int accumulatedTemperature = 0; + + while (position < memory.Length) { + cancellationToken.ThrowIfCancellationRequested(); + + // Read Unix timestamp delta (precision 0) then temperature delta. + if (!PolylineEncoding.TryReadValue(ref accumulatedTimestamp, memory, ref position) + || !PolylineEncoding.TryReadValue(ref accumulatedTemperature, memory, ref position)) { + yield break; + } + + long unixSeconds = (long)PolylineEncoding.Denormalize(accumulatedTimestamp, precision: 0); + double temperature = PolylineEncoding.Denormalize(accumulatedTemperature, Options.Precision); + + yield return new SensorReading(DateTimeOffset.FromUnixTimeSeconds(unixSeconds), temperature); + } + } +} diff --git a/samples/PolylineAlgorithm.SensorData.Sample/SensorDataEncoder.cs b/samples/PolylineAlgorithm.SensorData.Sample/SensorDataEncoder.cs new file mode 100644 index 00000000..be199e4d --- /dev/null +++ b/samples/PolylineAlgorithm.SensorData.Sample/SensorDataEncoder.cs @@ -0,0 +1,135 @@ +// +// Copyright © Pete Sramek. All rights reserved. +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// + +namespace PolylineAlgorithm.SensorData.Sample; + +using PolylineAlgorithm.Abstraction; +using System.Buffers; +using System.Threading; + +/// +/// Encodes a sequence of values into a compact polyline string +/// using the polyline delta-encoding algorithm applied to both the +/// and fields. +/// +/// +/// +/// This class demonstrates implementing for a custom +/// scalar type, following the same structural pattern as . +/// +/// +/// Because sensor readings carry two numeric dimensions (timestamp and temperature), the base class designed +/// for geographic coordinate pairs is not used. Instead, static +/// helpers are called directly to perform normalisation, delta computation, and character-level encoding. +/// +/// +/// Each reading is encoded as a pair of delta-compressed values: +/// the Unix timestamp in seconds (precision 0) followed by the temperature (at ). +/// +/// +internal sealed class SensorDataEncoder : IPolylineEncoder { + // 2020-01-01 00:00:00 UTC in Unix seconds. Used as the delta-encoding base for timestamps + // so that the first absolute delta stays within the int32 safe range of the polyline algorithm. + internal const int TimestampBaseEpochSeconds = 1_577_836_800; + + /// + /// Initializes a new instance of the class with default encoding options. + /// + public SensorDataEncoder() + : this(new PolylineEncodingOptions()) { } + + /// + /// Initializes a new instance of the class with the specified encoding options. + /// + /// + /// The to use for encoding operations. + /// + /// + /// Thrown when is . + /// + public SensorDataEncoder(PolylineEncodingOptions options) { + ArgumentNullException.ThrowIfNull(options); + + Options = options; + } + + /// + /// Gets the encoding options used by this encoder. + /// + public PolylineEncodingOptions Options { get; } + + /// + /// Encodes a sequence of values into a polyline string. + /// + /// + /// The sensor readings to encode. Each reading contributes a delta-compressed Unix timestamp + /// (seconds since Unix epoch, precision 0) and a delta-compressed temperature value. + /// Must contain at least one element. + /// + /// + /// A that can be used to cancel the encoding operation. + /// + /// + /// A polyline-encoded string representing the delta-compressed timestamp and temperature series. + /// + /// + /// Thrown when is empty. + /// + /// + /// Thrown when requests cancellation. + /// + public string Encode(ReadOnlySpan coordinates, CancellationToken cancellationToken = default) { + if (coordinates.Length < 1) { + throw new ArgumentException("Sequence must contain at least one element.", nameof(coordinates)); + } + + // Maximum number of ASCII characters required to encode a single 32-bit delta value + // using the polyline algorithm (ceil(32 bits / 5 bits per chunk) + sign bit = 7). + const int MaxEncodedCharsPerValue = 7; + + // Each reading encodes two values: Unix timestamp (precision 0) + temperature. + // The polyline algorithm uses signed int32 internally, limiting safe absolute values to ~1.07B. + // Current Unix time in seconds (~1.74B) exceeds this. We therefore delta-encode relative to + // 2020-01-01 00:00:00 UTC (= 1 577 836 800 s), keeping the initial delta well within range. + int previousTimestampNormalized = TimestampBaseEpochSeconds; + int previousTemperatureNormalized = 0; + int position = 0; + int length = coordinates.Length * 2 * MaxEncodedCharsPerValue; + + char[]? temp = length <= Options.StackAllocLimit + ? null + : ArrayPool.Shared.Rent(length); + + Span buffer = temp is null ? stackalloc char[length] : temp.AsSpan(0, length); + + try { + for (int i = 0; i < coordinates.Length; i++) { + cancellationToken.ThrowIfCancellationRequested(); + + // Encode Unix timestamp in whole seconds (precision 0). + int normalizedTimestamp = PolylineEncoding.Normalize((double)coordinates[i].Timestamp.ToUnixTimeSeconds(), precision: 0); + int timestampDelta = normalizedTimestamp - previousTimestampNormalized; + + // Encode temperature at the configured precision. + int normalizedTemperature = PolylineEncoding.Normalize(coordinates[i].Temperature, Options.Precision); + int temperatureDelta = normalizedTemperature - previousTemperatureNormalized; + + if (!PolylineEncoding.TryWriteValue(timestampDelta, buffer, ref position) + || !PolylineEncoding.TryWriteValue(temperatureDelta, buffer, ref position)) { + throw new InvalidOperationException("Encoding buffer is too small to hold the encoded value."); + } + + previousTimestampNormalized = normalizedTimestamp; + previousTemperatureNormalized = normalizedTemperature; + } + + return buffer[..position].ToString(); + } finally { + if (temp is not null) { + ArrayPool.Shared.Return(temp); + } + } + } +} diff --git a/samples/PolylineAlgorithm.SensorData.Sample/SensorReading.cs b/samples/PolylineAlgorithm.SensorData.Sample/SensorReading.cs new file mode 100644 index 00000000..6903c92f --- /dev/null +++ b/samples/PolylineAlgorithm.SensorData.Sample/SensorReading.cs @@ -0,0 +1,16 @@ +// +// Copyright © Pete Sramek. All rights reserved. +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// + +namespace PolylineAlgorithm.SensorData.Sample; + +using System.Runtime.InteropServices; + +/// +/// Represents a single temperature reading captured by a sensor. +/// +/// The UTC time at which the reading was captured. +/// The temperature value of the reading, in degrees Celsius. +[StructLayout(LayoutKind.Auto)] +internal readonly record struct SensorReading(DateTimeOffset Timestamp, double Temperature); diff --git a/src/PolylineAlgorithm/PolylineAlgorithm.csproj b/src/PolylineAlgorithm/PolylineAlgorithm.csproj index 24504239..907a2a15 100644 --- a/src/PolylineAlgorithm/PolylineAlgorithm.csproj +++ b/src/PolylineAlgorithm/PolylineAlgorithm.csproj @@ -8,6 +8,13 @@ True + + + $(WarningsAsErrors);RS0017 + + true diff --git a/src/PolylineAlgorithm/PolylineEncoding.cs b/src/PolylineAlgorithm/PolylineEncoding.cs index 4b8d5312..64b82c82 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))); } - } /// @@ -329,123 +330,75 @@ public static int GetRequiredBufferSize(int delta) { private const ushort End = (Defaults.Algorithm.QuestionMark + Defaults.Algorithm.Space); /// - /// SIMD vector containing the minimum valid character value for efficient range validation of polyline segments. - /// - private static readonly Vector MinVector = new(Min); - - /// - /// SIMD vector containing the maximum valid character value for efficient range validation of polyline segments. - /// - private static readonly Vector MaxVector = new(Max); - - /// - /// Validates the format of a polyline segment, ensuring all characters are valid and block structure is correct. + /// Validates a single encoded polyline segment for both character correctness and encoded-value block structure. /// /// /// - /// This method performs two levels of validation on the provided polyline segment: + /// The method performs two validations in a single linear pass over : /// /// /// /// - /// 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. + /// Character range: every character must be within the allowed ASCII range for the polyline algorithm + /// (from '?' (63) up to '_' (95), inclusive). If a character outside this range is encountered, an exception is raised + /// (see ). /// /// /// /// - /// Block Structure Validation: Ensures that each encoded value (block) does not exceed 7 characters and that the polyline ends with a valid block terminator. + /// Block structure: each encoded value is composed of one or more 5-bit chunks and must end with a terminator + /// (a character with value less than ). Blocks may not exceed the configured maximum length + /// (); violations raise + /// . The method also ensures the entire polyline ends with + /// a valid block terminator (). /// /// /// /// - /// If an invalid character or block structure is detected, an is thrown with details about the error. + /// Implementation notes: + /// + /// Time: O(n) where n is the number of characters in . + /// Memory: O(1) additional allocations (scalar single-pass validation). + /// For character-only validation that may benefit from SIMD/vectorization, use . + /// The method reports specific errors through the helpers: + /// , + /// , and + /// . + /// /// /// - /// A span representing the polyline segment to validate. + /// A span containing the encoded polyline segment to validate. /// - /// Thrown when an invalid character is found or the block structure is invalid. + /// Thrown when the polyline contains an invalid character, a block exceeds the maximum allowed length, or the polyline + /// does not end with a valid block terminator. Concrete exceptions are raised via . /// + /// Nothing. The method completes successfully if validation passes; otherwise it throws via . + /// + /// + /// // Validates an encoded segment and throws if malformed: + /// PolylineEncoding.ValidateFormat(somePolylineSpan); + /// + /// public static void ValidateFormat(ReadOnlySpan polyline) { - // 1. SIMD character check (reuse existing method) - ValidateCharRange(polyline); - // 2. Block structure check - ValidateBlockLength(polyline); - } - - /// - /// Validates that all characters in the polyline segment are within the allowed ASCII range for polyline encoding. - /// - /// - /// - /// 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. - /// - /// - /// A span representing the polyline segment to validate. - /// - /// Thrown when an invalid character is found in the polyline segment. - /// - public static void ValidateCharRange(ReadOnlySpan polyline) { - int length = polyline.Length; - int vectorSize = Vector.Count; - - int i = 0; - for (; i <= length - vectorSize; i += vectorSize) { - var span = MemoryMarshal.Cast(polyline.Slice(i, vectorSize)); -#if NET5_0_OR_GREATER - var chars = new Vector(span); -#else - var chars = new Vector(span.ToArray()); -#endif - var belowMin = Vector.LessThan(chars, MinVector); - var aboveMax = Vector.GreaterThan(chars, MaxVector); - if (Vector.BitwiseOr(belowMin, aboveMax) != Vector.Zero) { - // Fallback to scalar check for this block - for (int j = 0; j < vectorSize; j++) { - char character = polyline[i + j]; - if (character < Min || character > Max) { - ExceptionGuard.ThrowInvalidPolylineCharacter(character, i + j); - } - } - } - } - - for (; i < length; i++) { - char character = polyline[i]; - if (character < Min || character > Max) { - ExceptionGuard.ThrowInvalidPolylineCharacter(character, i); - } - } - } - - /// - /// Validates the block structure of a polyline segment, ensuring each encoded value does not exceed 7 characters and the polyline ends correctly. - /// - /// - /// - /// 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. - /// - /// - /// A span representing the polyline segment to validate. - /// - /// Thrown when a block exceeds 7 characters or the polyline does not end with a valid block terminator. - /// - public static void ValidateBlockLength(ReadOnlySpan polyline) { int blockLen = 0; bool foundBlockEnd = false; for (int i = 0; i < polyline.Length; i++) { + char c = polyline[i]; + + if (c < Min || c > Max) { + ExceptionGuard.ThrowInvalidPolylineCharacter(c, i); + } + blockLen++; - if (polyline[i] < End) { + if (c < End) { foundBlockEnd = true; + if (blockLen > Defaults.Polyline.Block.Length.Max) { ExceptionGuard.ThrowPolylineBlockTooLong(i - blockLen + 1); } + blockLen = 0; } else { foundBlockEnd = false; diff --git a/src/PolylineAlgorithm/PublicAPI.Shipped.txt b/src/PolylineAlgorithm/PublicAPI.Shipped.txt index 91b0e1a4..7dc5c581 100644 --- a/src/PolylineAlgorithm/PublicAPI.Shipped.txt +++ b/src/PolylineAlgorithm/PublicAPI.Shipped.txt @@ -1 +1 @@ -#nullable enable \ No newline at end of file +#nullable enable diff --git a/src/PolylineAlgorithm/README.md b/src/PolylineAlgorithm/README.md index d1bf97e0..97c4bb98 100644 --- a/src/PolylineAlgorithm/README.md +++ b/src/PolylineAlgorithm/README.md @@ -1,6 +1,8 @@ # PolylineAlgorithm for .NET -A modern, fully compliant Google Encoded Polyline Algorithm library for .NET Standard 2.1+, supporting strong input validation, extensibility for custom coordinate types, and robust performance. +[![NuGet](https://img.shields.io/nuget/v/PolylineAlgorithm)](https://www.nuget.org/packages/PolylineAlgorithm) + +Google's Encoded Polyline Algorithm compresses sequences of geographic coordinates into a compact ASCII string, widely used in mapping APIs. This library provides a fully compliant .NET implementation with extensible, type-safe encoding and decoding APIs. ## Features @@ -59,6 +61,7 @@ var encoder = new MyPolylineEncoder(); string encoded = encoder.Encode(coordinates); // extension method for List Console.WriteLine(encoded); +// Output: "yseiHoc_MwacOjnwM" ``` ### Implement a custom decoder @@ -84,8 +87,22 @@ IEnumerable<(double Latitude, double Longitude)> decoded = decoder.Decode(encode ## Advanced Usage -- Pass a `PolylineEncodingOptions` (built via `PolylineEncodingOptionsBuilder`) to the encoder/decoder constructor for custom precision, stack-alloc limit, and logging. -- Use static methods on `PolylineEncoding` for low-level normalization, validation, and bit-level read/write operations. +Use `PolylineEncodingOptionsBuilder` to customize precision, buffer size, and logging, then pass the built options to the encoder or decoder constructor: + +```csharp +using Microsoft.Extensions.Logging; + +PolylineEncodingOptions options = PolylineEncodingOptionsBuilder.Create() + .WithPrecision(6) // 6 decimal places instead of the default 5 + .WithStackAllocLimit(1024) // increase stack-alloc buffer + .WithLoggerFactory(loggerFactory) // plug in your ILoggerFactory + .Build(); + +var encoder = new MyPolylineEncoder(options); +var decoder = new MyPolylineDecoder(options); +``` + +Use static methods on `PolylineEncoding` for low-level normalization, validation, and bit-level read/write operations. > See [API Reference](https://petesramek.github.io/polyline-algorithm-csharp/) for full documentation. @@ -93,6 +110,8 @@ IEnumerable<(double Latitude, double Longitude)> decoded = decoder.Decode(encode - **What coordinate ranges are valid?** Latitude: -90..90, Longitude: -180..180 (throws `ArgumentOutOfRangeException` for invalid input) +- **What happens if I pass malformed input to the decoder?** + The decoder throws `InvalidPolylineException` with a descriptive message. Wrap calls in a try/catch in your application. - **What .NET versions are supported?** Any environment supporting `netstandard2.1` - **How do I customize encoder options?** @@ -100,6 +119,11 @@ IEnumerable<(double Latitude, double Longitude)> decoded = decoder.Decode(encode - **Where can I get help?** [GitHub issues](https://github.com/petesramek/polyline-algorithm-csharp/issues) +## Resources + +- [GitHub Repository](https://github.com/petesramek/polyline-algorithm-csharp) — source code, issues, changelog, and samples +- [API Reference](https://petesramek.github.io/polyline-algorithm-csharp/) — full auto-generated documentation + ## License MIT License © Pete Sramek diff --git a/tests/PolylineAlgorithm.Tests/PolylineEncodingTests.cs b/tests/PolylineAlgorithm.Tests/PolylineEncodingTests.cs index d598e3c2..2e7b1e0f 100644 --- a/tests/PolylineAlgorithm.Tests/PolylineEncodingTests.cs +++ b/tests/PolylineAlgorithm.Tests/PolylineEncodingTests.cs @@ -613,69 +613,4 @@ public void ValidateFormat_With_Block_Too_Long_Throws_InvalidPolylineException() } #endregion - - #region ValidateCharRange Tests - - /// - /// Tests that ValidateCharRange succeeds for valid polyline strings. - /// - [TestMethod] - [DataRow("_p~iF~ps|U_ulLnnqC_mqNvxq`@")] - [DataRow("?")] // min valid char (ASCII 63) - [DataRow("~")] // max valid char (ASCII 126) - [DataRow("")] // empty is valid - [DataRow("????????????????????????????????")] // long string to trigger SIMD path - public void ValidateCharRange_With_Valid_Polyline_Does_Not_Throw(string polyline) { - // Act & Assert - PolylineEncoding.ValidateCharRange(polyline); - } - - /// - /// Tests that ValidateCharRange throws for polylines containing invalid characters. - /// - [TestMethod] - [DataRow(">")] // ASCII 62 (below min of 63) - [DataRow("\u007F")] // ASCII 127 (above max of 126) - [DataRow("_p~iF!ps|U")] // '!' in middle (ASCII 33) - [DataRow("_p~iF~ps|U!")] // '!' at end - [DataRow("????????!???????????????????????")] // invalid in SIMD section - [DataRow("????????????????\u007F")] // invalid in scalar remainder - public void ValidateCharRange_With_Invalid_Character_Throws_InvalidPolylineException(string polyline) { - // Act & Assert - Assert.ThrowsExactly(() => PolylineEncoding.ValidateCharRange(polyline)); - } - - #endregion - - #region ValidateBlockLength Tests - - /// - /// Tests that ValidateBlockLength succeeds for valid block structures. - /// - [TestMethod] - [DataRow("?")] // single terminator - [DataRow("_p~iF~ps|U")] // multiple blocks - [DataRow("______?")] // 6 continuation chars + terminator (maximum block length) - [DataRow("??")] // consecutive terminators - [DataRow("?__?_____?")] // mixed block lengths - public void ValidateBlockLength_With_Valid_Polyline_Does_Not_Throw(string polyline) { - // Act & Assert - PolylineEncoding.ValidateBlockLength(polyline); - } - - /// - /// Tests that ValidateBlockLength throws for invalid block structures. - /// - [TestMethod] - [DataRow("________?")] // 8-char block (exceeds max of 7) - [DataRow("________")] // all continuation chars, no terminator - [DataRow("")] // empty polyline has no terminator - [DataRow("?________?")] // valid block then too-long block - [DataRow("________?_?")] // first block too long - public void ValidateBlockLength_With_Invalid_Polyline_Throws_InvalidPolylineException(string polyline) { - // Act & Assert - Assert.ThrowsExactly(() => PolylineEncoding.ValidateBlockLength(polyline)); - } - - #endregion }