[dkhawk]

Summary

Adds a public Units API (com.google.maps.android) to :library for type-safe distance and elevation representation, framework-agnostic unit system resolution, and KMP-compatible logical precision formatting.

Key Additions

• Physical Conversion Constants: Exact international foot (METERS_PER_FOOT = 0.3048, FEET_PER_METER = 1.0 / METERS_PER_FOOT) and statute mile (FEET_PER_MILE = 5_280, METERS_PER_MILE = 1609.344, MILES_PER_METER) constants alongside METERS_PER_KILOMETER = 1_000.
• Meters Inline Value Class: @JvmInline value class Meters(val value: Double) : Comparable<Meters> with +, -, *, /, unary -, Number construction extensions (.meters/.m, .kilometers/.km, .feet/.ft, .miles/.mi), and scalar conversions (.toMeters, .toKilometers, .toFeet, .toMiles).
• Framework-Agnostic UnitSystem & NumberFormatSymbols:
  • UnitSystem.METRIC and UnitSystem.IMPERIAL with fromLocale(locale = Locale.getDefault()) and fromCountryCode(countryCode) defaulting "US", "LR", "MM", and "GB" to IMPERIAL and all others to METRIC.
  • NumberFormatSymbols for KMP-friendly locale grouping and decimal separator resolution without relying on java.util.Formatter (String.format).
• Logical Precision Formatting (UnitsConverter, MetricUnitsConverter, ImperialUnitsConverter):
  • Switches from ft to mi at 0.25 miles (1,320 feet) and from m to km at 1,000 meters (1.0 km).
  • Formats small units (m below 1 km, ft below 0.25 mi, and all elevations) as whole integers (0 decimals, with locale thousands grouping, e.g., "450 m", "528 ft", "14,440 ft").
  • Formats medium distances (0.25 to < 10 mi, 1.0 to < 10 km) with 1 decimal digit, keeping the trailing .0 (e.g., "0.3 mi", "1.0 km", "2.0 km", "2.5 mi").
  • Formats large distances (>= 10 km or >= 10 mi) as whole integers (0 decimals, e.g., "10 km", "12 mi").
  • Supports both pure-Kotlin/JVM formatting (Locale / NumberFormatSymbols) and Android Resources formatting (amu_in_*), plus Double overloads for Java callers.
• Samples & Tests:
  • Added UnitsDemoActivity (Kotlin + Compose + GoogleMap) and updated DistanceDemoActivity (Java).
  • Added comprehensive unit test suites in UnitsTest and UnitsDemoTest.

Test Plan

• ./gradlew apiCheck spotlessCheck :library:testDebugUnitTest :demo:testStandardDebugUnitTest :library:lintDebug
• Verified UnitsDemoActivity and DistanceDemoActivity on emulator (emulator-5554) and Pixel 6.

[googlemaps-bot]

Code Coverage

Overall Project	63.08% -0.24%	🍏
Files changed	88.54%	🍏

Module	Coverage
Kover Gradle Plugin XML report for :library	89.49% -1.46%	🍏

Files

Module	File	Coverage
Kover Gradle Plugin XML report for :library	Units.kt	88.54% -11.46%	🍏