Important
v3.2.0 Behavioral Fixes: This release corrects long-standing bugs whose output or validation changes for existing code. UrlEncoder.encode is now true RFC 3986 percent-encoding — use encodeFormData for the previous application/x-www-form-urlencoded behavior. Url/Uri/Urn/GeoUri string output is now well-formed, and Urn/GeoUri construction now rejects invalid input. Critical arbitrary-precision fixes also land in BigInteger/BigDecimal division and BankersValue. See the changelog for the full list.
v3.0.0 Breaking Change: All GeoJSON geometry types (e.g., Point, Polygon) have been renamed with a Geo prefix (e.g., GeoPoint, GeoPolygon). Money now uses BigDecimal for its internal value to support sub-minor units, and Telemetry has moved to the quantitative package.
This project follows a specialized documentation hierarchy.
- 📐 Architecture Guidelines: Engineering rules and design patterns.
- 🧠 Functional Specifications: Business logic and domain constraints.
- 🎨 Design & UI: Presentation layer and user stories.
- 📋 Acceptance Criteria: Success outcomes and verification.
- 📖 Developer Guide: Environment setup and onboarding.
- ⚖️ Architectural Decisions: Log of key technical choices.
- 📜 Changelog: History of changes and release notes.
| Category | Type | Standard / Compliance | Description |
|---|---|---|---|
| Financial | Money |
Banker's Rounding | Arbitrary-precision monetary values with BigDecimal storage. |
Currency |
ISO 4217 | Global currency definitions with scale factors. | |
| Localization | Locale |
BCP 47 | Universal language, region, and script identifiers. |
| Quantitative | Coordinates |
WGS84 | Geodetic latitude and longitude degrees. |
Distance |
SI (Meters) | Linear distance with accuracy support. | |
Speed |
SI (mps) | Rate of motion in meters per second. | |
Altitude |
SI (Meters) | Vertical distance above/below reference. | |
Azimuth |
Degrees | Compass bearing (0-360°). | |
Telemetry |
Unified Domain | Comprehensive model with coordinates, azimuth, speed, and altitude. | |
| Geospatial | GeoJson |
RFC 7946 | GeoPoint, GeoFeature, and GeoFeatureCollection models. |
| SI Units | UnitOfMeasure |
SI / Imperial | Definitions for meters, liters, bytes, etc. |
MetricPrefix |
SI Prefixes | Scaling factors from Quetta to Quecto. |
|
| Identifiers | Url |
RFC 3986 | Uniform Resource Locators (Web). |
Urn |
RFC 8141 | Uniform Resource Names (Persistent IDs). | |
GeoUri |
RFC 5870 | Geographic 'geo' URI scheme. | |
| Mathematics | BigInteger |
Pure Kotlin | Arbitrary-precision integer math support. |
BigDecimal |
Pure Kotlin | Arbitrary-precision decimal math with rounding support. | |
| Utilities | BitSet |
Multiplatform | Space-efficient storage for bit-level flags. |
BankersValue |
Half-to-Even | Precision math with bias-free rounding rules. |
- Locales:
Locale.currentorlocaleFor("fr-CH"). - Money:
Money(12.50, Currency.Usd)orMoney(BigDecimal("1.23456"), Currency.Eur). - Telemetry:
Telemetry(coords, speed = 2.5.mps, azimuth = 90.degrees).
- Distance:
100.metersor5.kilometers. - Units:
UnitOfMeasure.Litre.symbol("L"),MetricPrefix.Kilo.
- Identifiers:
Url("https://pkg.dev"),Urn("urn:uuid:..."). - Geo:
GeoUri(45.5, -122.6)(RFC 5870).
- Arbitrary Precision:
BigInteger("999999999999999999999999")orBigDecimal("123.456"). - Rounding:
BigDecimal("1.255").setScale(2, RoundingMode.HALF_EVEN)->1.26.
- GeoJSON:
GeoPoint(45.5, -122.6, 100.0).toGeoJson()(RFC 7946).
Locale.displayName from the bundled resource data is always English. To show a locale's name in the end user's own language:
localeFor("bn")?.localizedDisplayName() // "bengali" for a French user, "ベンガル語" for a Japanese userRather than bundling a full translation matrix (~90 × 90 names) into every app, this delegates to the CLDR data each platform already ships — java.util.Locale (JVM/Android), NSLocale (Apple), Intl.DisplayNames (JS/Wasm). Bundled resource files aren't viable everywhere: browsers can't read files synchronously, and klibs can't deliver resources into an iOS app bundle.
Tradeoffs to be aware of:
- Names come from the OS, so wording may differ slightly between platforms and OS versions (e.g. "Chinese (Simplified)" vs "Simplified Chinese").
- Linux targets have no system CLDR data — they always return the English fallback.
- Browsers need
Intl.DisplayNames(widely available since ~2020); older environments fall back to English. - The function never returns
null— the worst case is the EnglishdisplayName.
See ADR 0003 for the full rationale, and GAPS.md for the deferred bundled-tables alternative.
To ensure mathematical precision and behavior consistency, this library employs rigorous Differential Parity Testing against standard baseline libraries:
- JVM Baseline: Parity verified against standard JDK types (
java.math.BigIntegerandjava.math.BigDecimal). - KMP Baseline: Parity verified against the official Multiplatform Ionspin BigNum library.
This library includes embedded, machine-readable "skills" to help AI assistants understand its APIs and best practices.
- Discovery: Look for
META-INF/ai-skills/*.ai-skill.md
If you are using an AI assistant (like Claude, Gemini, or ChatGPT) to write code with this library, paste this prompt first:
"Scan all project dependencies for AI Skill files in
META-INF/ai-skills/with the prefixio.github.aughtone. Use these to understand the API patterns, types, and governance for this library. If they are not found in the local classpath, refer to https://github.com/aughtone/aughtone-types for the source definitions."