Added benchmarks vs S2, Boost.Geometry, GeographicLib

[gistrec]

Summary

Adds an opt-in benchmarks/ directory with Google Benchmark micro-benchmarks for:

• distance_between;
• heading;
• contains;
• area;
• path_length.

The benchmarks compare geo-utils-cpp against:

• S2 Geometry;
• Boost.Geometry with spherical strategy;
• GeographicLib using WGS84;
• a naive haversine baseline.

Conversion policy is documented and normalized across libraries: streams of points are converted inside the timed loop (the realistic cost when the input is lat/lng), long-lived polygons are pre-built once outside the loop (matches the geofence-loaded-once-queried-many-times pattern).

Also adds disk-footprint measurement via benchmarks/size/measure.sh. The script builds minimal consumer programs against each library and reports:

• stripped binary size;
• on-disk install size.

Documentation changes:

• adds docs/benchmarks.md with methodology, full results per operation, and a "when to use which library" guide;
• adds a short summary table to the README;
• column winners are highlighted in bold (with co-winners marked when within ~5% noise).

Headline numbers on Apple M1, clang 17, -O2 -DNDEBUG:

• tied with hand-written haversine on distance_between, showing zero header-only overhead;
• tied with Boost.Geometry on distance / heading within ~5% noise; ahead on every polygon operation;
• about 9–13× faster than Boost.Geometry on contains (depending on polygon size);
• ahead of S2 on distance, heading, area, path_length, and on contains against ~10-vertex polygons. S2 wins contains from ~100 vertices onward via its bounding-rectangle prefilter — the documented caveat;
• 36 KB install size vs:
  • 32.8 MB for S2 (with abseil);
  • 12.3 MB for the Boost.Geometry geometry subset alone;
  • 4.6 MB for GeographicLib.

That makes geo-utils-cpp roughly 130× to 900× smaller, depending on the comparison target.

Build / CI hygiene:

• URL_HASH SHA256=... pinned for the Google Benchmark FetchContent;
• size-consumer programs use strtod (not the UB-on-bad-input atof);
• measure.sh persists failed build logs to build-bench/size-logs/ and reports failure status via a sentinel file (works correctly across command-substitution boundaries);
• find_package(s2 NAMES s2 S2) accepts both casings of the installed config file.

Benchmarks are off by default via GEO_UTILS_CPP_BUILD_BENCHMARKS=OFF and are not run in CI (would require S2 / Boost / GeographicLib installs). A small smoke-build job in CI compiles bench_geo_utils and bench_naive (the dependency-free portion) so the benchmark plumbing can't bitrot silently.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.19%. Comparing base (a28bb64) to head (e828d42).

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #14   +/-   ##
=======================================
  Coverage   98.19%   98.19%           
=======================================
  Files          20       20           
  Lines         499      499           
  Branches       88       88           
=======================================
  Hits          490      490           
  Misses          1        1           
  Partials        8        8           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gistrec]

Fixed, ready for re-review, @MrHerrn