feat: add Units API for distance and elevation conversion and formatting by dkhawk · Pull Request #1832 · googlemaps/android-maps-utils

dkhawk · 2026-10-22T15:17:45Z

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 · 2026-10-23T17:03:34Z

Code Coverage

Overall Project	63.69% `-0.34%`	🍏
Files changed	91.42%	🍏

Module	Coverage
Kover Gradle Plugin XML report for :library	90.02% `-1.88%`	🍏

Files

Module	File	Coverage
Kover Gradle Plugin XML report for :library	Units.kt	91.42% `-8.58%`	🍏

…L.md

snippet-bot · 2026-10-26T19:14:49Z

Here is the summary of changes.

You are about to add 10 region tags.

demo/src/main/java/com/google/maps/android/utils/demo/DistanceDemoActivity.java:70, tag maps_android_utils_units_java
demo/src/main/java/com/google/maps/android/utils/demo/UnitsDemoActivity.kt:63, tag maps_android_utils_units_kotlin
demo/src/main/java/com/google/maps/android/utils/demo/UnitsDemoActivity.kt:71, tag maps_android_utils_units_demo_model
demo/src/main/java/com/google/maps/android/utils/demo/UnitsDemoActivity.kt:210, tag maps_android_utils_units_demo_formatting
library/src/main/java/com/google/maps/android/Units.kt:39, tag maps_android_utils_units_constants
library/src/main/java/com/google/maps/android/Units.kt:68, tag maps_android_utils_units_meters
library/src/main/java/com/google/maps/android/Units.kt:153, tag maps_android_utils_units_system
library/src/main/java/com/google/maps/android/Units.kt:789, tag maps_android_utils_units_converters
library/src/main/java/com/google/maps/android/Units.kt:1327, tag maps_android_utils_units_pure_kotlin_formatter
library/src/test/java/com/google/maps/android/UnitsJavaTest.java:64, tag maps_android_utils_units_java_conversions

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

Refresh this comment

kikoso · 2026-10-28T10:00:40Z

+            val groupingSize = if (decimalFormat != null && decimalFormat.isGroupingUsed) {
+                decimalFormat.groupingSize
+            } else {
+                3


When the locale does not use grouping we fall back to 3, so we would still group the digits. The KDoc says <= 0 disables grouping, so shouldn't we return 0 here?

Suggested change

3

0

Good catch! Updated NumberFormatSymbols.fromLocale so that when decimalFormat == null || !decimalFormat.isGroupingUsed, groupingSize is set to 0 (disabling grouping) rather than falling back to 3. Also added a unit test verifying that NumberFormatSymbols.fromLocale returns groupingSize = 0 when isGroupingUsed == false.

kikoso · 2026-10-28T10:01:42Z

+    override val unitSystem: UnitSystem = UnitSystem.METRIC
+
+    override fun toDistanceUnits(meters: Meters): ValueWithUnitsTemplate =
+        if (abs(meters.value) < KILOMETERS_THRESHOLD.value) {


There is an edge case right below the threshold: 999.6 m stays in the meters branch but rounds up when formatted, so we get "1,000 m" instead of "1.0 km" (same for 1,319.6 ft, which shows as "1,320 ft" instead of "0.3 mi"). We already handle this for the 10 km/mi switch with isUnderTenAtOneDecimal. Could we compare the rounded value here too, and add a test near the threshold?

Great catch on the boundary rounding! Updated both MetricUnitsConverter.toDistanceString and ImperialUnitsConverter.toDistanceString to compare the rounded integer value in small units (abs(metersValue).roundToLong() < METERS_PER_KILOMETER and abs(feet).roundToLong() < THRESHOLD_FEET, clamping the miles magnitude to at least 0.25 once rounded feet reach 1,320 ft). Now 999.6.meters formats as "1.0 km" instead of "1,000 m", and 1_319.6.feet formats as "0.3 mi" instead of "1,320 ft". Added unit tests for both boundaries in UnitsTest and UnitsJavaTest.

kikoso · 2026-10-28T10:02:44Z

+    Distance or elevation in feet, formatted to 0 decimal places.
+    For example, 1234.56 feet will be formatted as "1,235 ft".
+    -->
+    <string name="amu_in_feet" translatable="false">%1$,.0f ft</string>


Just to understand it: since all the templates are translatable="false", the Resources overloads produce the same output as the pure Kotlin path (formatWithTemplate), and we end up with two code paths to keep in sync. Should we either make the unit labels translatable, or drop the Resources overloads and the resource IDs from the public API?

Great observation! We went with the first option (making the unit templates translatable while unifying onto a single number-formatting code path):

Translatable %1$s Unit Templates (amu_in_feet, amu_in_miles, amu_in_meters, amu_in_kilometers): Removed translatable="false", switched the placeholders from %1$,.0f / %1$,.1f to %1$s (cutting the resource count from 6 to 4 by dropping amu_in_miles_whole and amu_in_kilometers_whole), and added 24 localized values-<locale>/strings.xml translations (e.g., ja, ko, zh-rCN, zh-rTW, ru, uk, ar, fr, hi, th, el, iw, etc.).

Single Number-Formatting Code Path: Both the pure-Kotlin/KMP NumberFormatSymbols path and the Android Resources path now share the exact same formatDistance / NumberFormatSymbols rounding and grouping logic (ValueWithUnitsTemplate and String.format are gone), and callers can also compose or customize converters via UnitsConverter(...) / UnitsConverter.create(...).

kikoso · 2026-10-28T10:03:45Z

+ */
+public object ImperialUnitsConverter : UnitsConverter() {
+    /** Threshold (`0.25` miles = `1,320` feet) at which imperial distances switch from feet to miles. */
+    public val MILES_THRESHOLD: Meters = 0.25.miles


Since Meters is a value class, the getter gets mangled (getMILES_THRESHOLD-NA-LpbA in library.api) and can't be called from Java. Could we add @get:JvmName here and on KILOMETERS_THRESHOLD, or expose them as Double constants?

Added @get:JvmName("getMilesThreshold") on ImperialUnitsConverter.MILES_THRESHOLD and @get:JvmName("getKilometersThreshold") on MetricUnitsConverter.KILOMETERS_THRESHOLD so Java callers can invoke getMilesThreshold() and getKilometersThreshold() without inline value class mangling (verified in library.api and UnitsJavaTest).

kikoso · 2026-10-28T10:04:47Z

+
+/** Shorthand to create a [Meters] measurement from a [Number] of meters. */
+@get:JvmName("m")
+public inline val Number.m: Meters


I wonder if we could drop the short aliases (m, ft, mi, km). Being these extensions on Number in our root package, anyone importing them gets 5.m in autocompletion, and m is quite likely to clash with other libraries. The long forms read well enough, what do you think?

Agreed — since com.google.maps.android is the root package, single/two-letter extensions (m, km, ft, mi) on Number are too prone to autocomplete noise and collisions. Removed .m, .km, .ft, and .mi and kept the explicit .meters, .kilometers, .feet, and .miles extensions.

kikoso · 2026-10-28T10:05:48Z

+
+/** Returns the equivalent number of international feet for this [Meters] measurement. */
+@get:JvmName("toFeet")
+public inline val Meters.toFeet: Double


nit: in Kotlin to* names are usually functions, so meters.toFeet reads a bit like it is missing the (). What about inFeet / inMiles / inKilometers, similar to how Duration exposes its values?

Renamed toMeters, toKilometers, toFeet, and toMiles to inMeters, inKilometers, inFeet, and inMiles (including @get:JvmName("inMeters"), etc. for Java static imports) to match Kotlin's Duration naming convention (inWholeMeters / toDouble(DurationUnit)).

kikoso · 2026-10-28T10:06:50Z

+         * and elevations: United States (`"US"`), Liberia (`"LR"`), Myanmar (`"MM"`), and
+         * United Kingdom (`"GB"`).
+         */
+        public val IMPERIAL_COUNTRY_CODES: Set<String> = setOf("US", "LR", "MM", "GB")


Out of curiosity, is GB meant to apply to elevations too? In the UK road distances are in miles, but elevations (e.g. Ordnance Survey maps) are in meters, so "14,440 ft" may look odd there. Not a blocker, but maybe worth documenting, or splitting the distance and elevation systems later.

Great point! Updated UnitSystem (distanceFromLocale / elevationFromLocale) and getUnitsConverter so that "GB" (Locale.UK) defaults out-of-the-box to Imperial road distances (ft / mi) and Metric elevations (m), and added simple ways to override either distance or elevation (converter.withDistanceUnits(...), converter.withElevationUnits(...), getUnitsConverter(locale, distanceUnits = ..., elevationUnits = ...), and UnitsConverter(distanceUnits, elevationUnits)).

kikoso

Hi @dkhawk ! Nice addition, and very well documented. Can you take a look at the comments? Thanks! Since #1830 (7.0.0) is still open, this feat would ride along with that release, which works for me.

…nits - Default `groupingSize` to `0` in `NumberFormatSymbols.fromLocale` when `!decimalFormat.isGroupingUsed` - Fix threshold boundary rounding in `MetricUnitsConverter` (`999.6 m` -> `"1.0 km"`) and `ImperialUnitsConverter` (`1,319.6 ft` -> `"0.3 mi"`) - Replace `translatable="false"` numeric templates with 4 translatable `%1$s` unit templates (`amu_in_feet`, `amu_in_miles`, `amu_in_meters`, `amu_in_kilometers`), add 24 localized `values-<locale>/strings.xml` translations, and unify `Locale` and `Resources` formatting onto a single `NumberFormatSymbols` code path - Add `@get:JvmName("getMilesThreshold")` and `@get:JvmName("getKilometersThreshold")` for Java interop - Remove short `Number.m`, `.km`, `.ft`, and `.mi` extensions and rename `Meters.to*` properties to `inMeters`, `inKilometers`, `inFeet`, and `inMiles` - Default `"GB"` (`Locale.UK`) out-of-the-box to Imperial road distances (`ft`/`mi`) + Metric elevations (`m`), and add `withDistanceUnits`, `withElevationUnits`, `withDistanceConverter`, `withElevationConverter`, `withDistanceFormatter`, `withElevationFormatter`, and `UnitsConverter(...)` / `UnitsConverter.create(...)` overloads - Update `README.md`, `llm-integration-prompt.md`, `.gemini/skills/android-maps-utils/SKILL.md`, and unit tests (`UnitsTest`, `UnitsJavaTest`, `UnitsDemoTest`)

dkhawk · 2026-10-28T23:57:00Z

I am seeking to have a good general purpose distance / elevation formatting tool that we can use in the scale bar fix.

…esholds for ScaleBar - Add `trimTrailingZeros: Boolean = false` and `NumberFormatSymbols.COMPACT` (`groupingSize = 0`, `trimTrailingZeros = true`) for compact widgets like `ScaleBar` - Add `ImperialUnitsConverter(milesThreshold = ...)` / `ImperialUnitsConverter.withMilesThreshold(...)` and `MetricUnitsConverter(kilometersThreshold = ...)` / `MetricUnitsConverter.withKilometersThreshold(...)` - Add `ScaleBar` distance formatting tests matching `googlemaps/android-maps-compose#1045` (`ScaleBarDistanceTest` and `ScaleBarRenderingTests`) - Update `library.api` and documentation examples

dkhawk added 2 commits October 22, 2026 07:40

feat: add Units API for distance and elevation conversion and formatting

2a267cd

fix(demo): read LocalLocale.current.platformLocale in UnitsControlPanel

4b9ea46

github-advanced-security Bot found potential problems Oct 23, 2026

View reviewed changes

Comment thread demo/src/main/java/com/google/maps/android/utils/demo/UnitsDemoActivity.kt Fixed

dkhawk added 2 commits October 23, 2026 14:05

feat(units): expose clean Java conversion methods and fix UseKtx lint

022ebcc

docs(skill): document Units API with Kotlin and Java examples in SKIL…

113f247

…L.md

dkhawk marked this pull request as ready for review October 26, 2026 19:14

dkhawk requested a review from kikoso October 26, 2026 19:14

dkhawk assigned kikoso Oct 26, 2026

kikoso reviewed Oct 28, 2026

View reviewed changes

kikoso mentioned this pull request Oct 28, 2026

fix(widgets): preserve fractional scale bar distances googlemaps/android-maps-compose#1045

Merged

dkhawk requested a review from kikoso October 28, 2026 23:22

dkhawk added 2 commits October 30, 2026 13:10

feat(units): improve Java API ergonomics and expand Java test coverage

5af1f55

Conversation

dkhawk commented Oct 22, 2026

Summary

Key Additions

Test Plan

Uh oh!

Uh oh!

googlemaps-bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage

Uh oh!

snippet-bot Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kikoso left a comment

Choose a reason for hiding this comment

Uh oh!

dkhawk commented Oct 28, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

googlemaps-bot commented Oct 23, 2026 •

edited

Loading

snippet-bot Bot commented Oct 26, 2026 •

edited

Loading