Data formatting utilities for converting relative time, duration, file sizes, and numbers into human-readable formats. Supports localization with multiple languages and auto-switching to larger units for precision.
A small set of data formatting utilities for Kotlin Multiplatform (KMP).
This library only supports kotlinx-datetime.
The library is published to Maven Central.
Note: HumanReadable 1.12+ requires kotlinx-datetime 0.7+, see https://github.com/jacobras/Human-Readable/issues/148.
dependencies {
implementation("nl.jacobras:Human-Readable:1.13.0")
}
An interactive demo is available at https://jacobras.github.io/Human-Readable/.
HumanReadable.timeAgo(now - 134.minutes) // "2 hours ago"
HumanReadable.timeAgo(now + 8.minutes) // "in 8 minutes"
HumanReadable.duration(5.seconds) // "5 seconds"
HumanReadable.duration(7.days) // "1 week"
HumanReadable.duration(544.hours) // "3 weeks"
Note: The formatter switches to a bigger unit (minute, hour, day, ...) as soon as it can. See Precision.
File size formatting uses base 1024.
HumanReadable.fileSize(333) // "333 B"
HumanReadable.fileSize(2_048, decimals = 1) // "2.0 kB"
HumanReadable.fileSize(21_947_282_882, decimals = 2) // "20.44 GB" in English / "20.44 Go" in French
Available since version 1.8, localized since 1.10.
HumanReadable.abbreviation(3_000) // "3K"
HumanReadable.abbreviation(500_000) // "500K"
HumanReadable.abbreviation(2_500_000, decimals = 1) // "2.5M"
Available since version 1.10.
// English/default
HumanReadable.number(1_000_000.34) // "1,000,000.34"
// French
HumanReadable.number(1_000_000.34) // "1 000 000.34"
// Dutch
HumanReadable.number(1_000_000.34) // "1.000.000,34"
Available since version 1.11.
// Metric examples
HumanReadable.distance(value = 956, unit = DistanceUnit.Meter) // "956 m"
HumanReadable.distance(value = 1534, unit = DistanceUnit.Meter) // "1.5 km"
HumanReadable.distance(value = 5400, unit = DistanceUnit.Meter, decimals = 2) // "5.40 km"
// Imperial examples
HumanReadable.distance(value = 5200, unit = DistanceUnit.Foot)
HumanReadable.distance(value = , unit = DistanceUnit.Foot)
HumanReadable.distance(value = , unit = DistanceUnit.Foot, decimals = )
Note: numbers in meters and feet are always formatted with 0 decimals. The passed in number of decimals is only used for the larger units kilometers and miles.
The formatter switches to a bigger unit (minute, hour, day, ...) as soon as it can. For example:
59.seconds is "59 seconds" but 60.seconds becomes "1 minute"6.days is "6 days" but 7.days becomes "1 week"29.days is "29 days" but 30.days becomes "1 month"There's also some rounding involved:
8.days and 10.days are "1 week", but 11.days already becomes "2 weeks"This behaviour may become configurable in future releases.
The library uses the small Libres library for its string resources. It detects the current locale by default, but it's changeable on runtime. See Libres: Changing Localization.
You don't need to manually import Libres, as Gradle already pulls it in along with HumanReadable.
HumanReadable.timeAgo(instant) // "3 days ago"
LibresSettings.languageCode = "nl"
HumanReadable.timeAgo(instant) // "3 dagen geleden"
LibresSettings.languageCode = "fr"
HumanReadable.timeAgo(instant) // "il y a 3 jours"
Missing a language? Feel free to open an issue about it. Or, add it yourself:
time_units_[LANGUAGE CODE].xml (see Unicode: CLDR chart for the code & plural categories).data_units_[LANGUAGE CODE].xml.Surfaced from shared tags and platforms — no rankings paid for.