Skip to content

conformance: cover the edge, count and convenience functions it skipped - #187

Merged
justinhwang merged 1 commit into
masterfrom
conformance/edge-api-coverage
Nov 19, 2026
Merged

justinhwang merged 1 commit into
masterfrom
conformance/edge-api-coverage

Conversation

@justinhwang

@justinhwang justinhwang commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

I audited the public API against the conformance suite: every function in the v4.6.0 h3api.h, and every exported Go function and method. Several were not held to the reference by any record or runner check. This PR covers them.

New reference data

Two functions need the reference's answers, so the edges group records them. Both are computed from the edges each record already writes, with no new random draws:

Key Function
reverses reverseDirectedEdge(e) for each edge
vertexes edgeToVertexes(e) for each edge, as [start, end] (new in v4.6.0)

Only edges/cells.jsonl and its manifest hash change. With the two keys removed, every record is byte for byte the same as before, and the record count stays at 542.

Checks derived from existing data

These follow from data the suite already records, so the runner checks them without regenerating:

Go function Checked against
DirectedEdge#Cells the subject cell and the recorded destination
GridDiskDistancesSafe the recorded rings, as GridDiskDistances already is
GridDisksUnsafe (one origin) the recorded diskUnsafe outcome, and otherwise GridDiskUnsafe's cells
ImmediateParent, ImmediateChildren the last recorded parent, and the recorded children
NumCells each resolution's digest count
Pentagons twelve valid pentagons at the resolution, in ascending order

NumCells and Pentagons don't enumerate the grid, so they run for every resolution regardless of H3_CONFORMANCE_DIGESTS_MAXRES.

The README spec gains the two keys, a fresh example row taken from the regenerated file, and the checks a consumer in another language should also make: directedEdgeToCells, gridDiskDistancesSafe, getNumCells and getPentagons.

Not covered, on purpose

  • Free-function wrappers such as CellToBoundary, CellToVertexes, VertexToLatLng and CellToChildPos, plus GeoPolygon.Cells. Each is a one-line call to a method the suite already checks.
  • Go-only helpers: MarshalText/UnmarshalText, LatLngToCellString, NewLatLng. They have no C counterpart and are covered by unit tests.
  • C functions with no Go counterpart: describeH3Error, maxGridRingSize, res0CellCount, pentagonCount. Go uses error values and constants for these.
  • stringToH3 on invalid input. Where C returns an error, Go's IndexFromString returns a sentinel (0 for an empty string or a non-hex character, all ones on overflow) and leaves validation to the caller. Valid strings are parsed throughout the suite.

Testing

  • The conformance and root test suites pass, and lint is clean.
  • Swapping the return order of Vertexes or of Cells makes TestEdges fail, with 3,060 failed assertions each.
  • The generator builds under -Wall -Wextra -Werror -pedantic.

An audit of the public API against the suite found functions that no
record or runner check held to the reference.

Two need the reference's answers, so the edges group records them,
computed from the edges it already writes with no new draws:

- reverses: reverseDirectedEdge for each edge.
- vertexes: edgeToVertexes for each edge, as its start and end vertex.
  The function is new in v4.6.0.

Only edges/cells.jsonl and its manifest hash change. With the two keys
removed, every record is byte for byte the same as before.

The rest follow from data the suite already has, so the runner checks
them without regenerating:

- DirectedEdge#Cells is the subject cell and the recorded destination.
- GridDiskDistancesSafe is built from the rings, as GridDiskDistances is.
- GridDisksUnsafe on one origin refuses exactly when GridDiskUnsafe does,
  and otherwise returns the same cells.
- ImmediateParent and ImmediateChildren are the last recorded parent and
  the recorded children.
- NumCells is each resolution's digest count, and Pentagons returns
  twelve valid pentagons in ascending order. Neither enumerates the grid,
  so every resolution is checked, however many a run digests.

The README spec gains the two keys, a fresh example row, and the checks a
consumer in another language should also make.

Swapping the return order of Vertexes or Cells makes TestEdges fail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coveralls

Copy link
Copy Markdown

Coverage Report for CI Build 44578498678

Coverage remained the same at 100.0%

Details

  • Coverage remained the same as the base build.
  • Patch coverage: No coverable lines changed in this PR.
  • No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 4094
Covered Lines: 4094
Line Coverage: 100.0%
Coverage Strength: 6206029.18 hits per line

💛 - Coveralls

@justinhwang
justinhwang merged commit 1bcdd18 into master Nov 19, 2026
16 checks passed
@justinhwang
justinhwang deleted the conformance/edge-api-coverage branch November 19, 2026 17:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants