Skip to content

Document edge-case behavior in api.md #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gistrec wants to merge 1 commit into
base: fix/docs-and-test-helpers
Choose a base branch
from
Open

Document edge-case behavior in api.md #31

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,12 @@ std::cout << geo::heading(equator, east); // +90 (due east)
std::cout << geo::heading(east, equator); // -90 (due west)
```

> **Note.** When `from == to`, or the two points are exactly antipodal,
> the heading is mathematically undefined. The returned value is
> unspecified and may differ across platforms (e.g. `0` or `-180`,
> depending on how the compiler contracts floating-point operations
> into FMA instructions).

---

### offset
Expand Down Expand Up @@ -198,6 +204,12 @@ assert(geo::LatLng{1, 0} == geo::interpolate(front, up, 1 / 90.0));
assert(geo::LatLng{89, 0} == geo::interpolate(front, up, 89 / 90.0));
```

> **Note.** Exactly antipodal endpoints have no unique great circle, so
> the result is unspecified. Nearly antipodal endpoints (central angle
> within ~`1e-6` rad of 180°) fall back to linear interpolation in raw
> `(lat, lng)` space and can land thousands of kilometers off any true
> arc — behavior inherited from android-maps-utils.

---

### angle_between
Expand Down Expand Up @@ -314,6 +326,11 @@ std::cout << geo::contains(geo::LatLng{90, 0}, aroundNorthPole); // true
std::cout << geo::contains(geo::LatLng{-90, 0}, aroundNorthPole); // false
```

> **Note.** An edge whose endpoints lie exactly 180° of longitude apart
> has an ambiguous direction — two equal-length arcs connect them. Such
> edges are never counted as crossed by the point-in-polygon test
> (android-maps-utils convention).

---

### on_edge
Expand Down Expand Up @@ -366,6 +383,11 @@ Returns: `double` — distance in meters, always ≥ 0.
> percent at high latitudes (around `lat 80°`); and longitudes are used as-is,
> so segments crossing the antimeridian (`±180°`) yield meaningless results —
> a point lying exactly on such a segment can report kilometers of distance.
> Degenerate segments are detected with the approximate `LatLng` equality
> (longitudes compared modulo 360°), so `start == end` — including pairs
> like `(0, -180)` and `(0, 180)` — returns the plain distance to that
> point. The Java original compares coordinates exactly here; this port
> deliberately diverges.
> For tolerance checks against true geodesic segments, use `on_path`.

```cpp
Expand Down