Document edge-case behavior in api.md#31
Open
gistrec wants to merge 1 commit into
Open
Conversation
- heading: result for from == to / exact antipodes is unspecified and platform-dependent (FMA contraction). - interpolate: exact antipodes unspecified; near-antipodal pairs fall back to linear interpolation (inherited from android-maps-utils). - contains: edges spanning exactly 180 degrees of longitude are never counted as crossed (upstream convention, fixed in #29). - distance_to_segment: degenerate segments detected via approximate LatLng equality (lng modulo 360) — deliberate divergence from Java.
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents four previously unspecified or divergent behaviors in
docs/api.md. Docs-only change, no code touched.heading— whenfrom == toor the points are exactly antipodal, the heading is mathematically undefined; the returned value is unspecified and platform-dependent (e.g.0vs-180depending on FMA contraction; observed difference between x86 and ARM clang).interpolate— exactly antipodal endpoints have no unique great circle (result unspecified); nearly antipodal endpoints (within ~1e-6 rad of 180°) hit the linear-interpolation fallback and can be thousands of kilometers off any true arc. Behavior inherited from android-maps-utils.contains— edges spanning exactly 180° of longitude have an ambiguous direction and are never counted as crossed (android-maps-utils convention). Documents the behavior fixed in Fix contains() for polygon edges spanning exactly 180° of longitude #29.distance_to_segment— degenerate segments are detected with the approximateLatLngequality (longitudes modulo 360°), so pairs like(0, -180)/(0, 180)collapse to a point. Deliberate divergence from the Java original, which compares exactly. Extends the Approximation note added in Document distance_to_segment limits; fix epsilon doc and test helper #26.Not added: a
geodesic-defaults note — already documented on master. Verified against upstreamPolyUtil.kt: it has nogeodesicdefaults at all (onlytolerance = DEFAULT_TOLERANCE), so the defaults are this port's own documented choice.Stacking
fix/docs-and-test-helpers(Document distance_to_segment limits; fix epsilon doc and test helper #26) to avoid conflicts in thedistance_to_segmentsection; retarget tomasterafter Document distance_to_segment limits; fix epsilon doc and test helper #26 merges.containsnote describes post-Fix contains() for polygon edges spanning exactly 180° of longitude #29 behavior — merge Fix contains() for polygon edges spanning exactly 180° of longitude #29 before or together with this.Test plan
docs/api.md(four new blockquote notes).