HumanReadable

The library automatically switches to a larger unit as soon as the threshold is met, and includes some rounding logic:

• 59.seconds $\rightarrow$ "59 seconds"; 60.seconds $\rightarrow$ "1 minute"
• 6.days $\rightarrow$ "6 days"; 7.days $\rightarrow$ "1 week"
• 29.days $\rightarrow$ "29 days"; 30.days $\rightarrow$ "1 month"
• Rounding: 8.days and 10.days both result in "1 week", but 11.days becomes "2 weeks".

Add the HumanReadable dependency to your Kotlin Multiplatform project.

Requirement: HumanReadable 1.12+ requires kotlinx-datetime 0.7+.

dependencies {
    implementation("nl.jacobras:Human-Readable:1.13.1")
}

To run the Human-Readable web demo in a development environment using the Gradle wrapper, execute the following command from the repository root:

./gradlew :demo:jsBrowserDevelopmentRun

To publish the web demo to the /docs directory for repository hosting, follow these steps:

1. Build the production distribution using the Compose Web compatibility task: gradlew :demo:composeCompatibilityBrowserDistribution
2. Copy the generated files from /demo/build/dist/composeWebCompatibility/productionExecutable into the /docs directory.
3. Push the updated /docs directory to your repository.

# 1. Build
./gradlew :demo:composeCompatibilityBrowserDistribution

# 2. Copy (Manual step)
# cp -r /demo/build/dist/composeWebCompatibility/productionExecutable/* /docs/

# 3. Push
# git add docs && git commit -m "Update web demo" && git push

HumanReadable uses the Libres library for localization. It detects the current locale by default, but you can change it at runtime by setting LibresSettings.languageCode.

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"

Use HumanReadable.duration(duration) to convert a duration into a human-readable string. The formatter automatically switches to the largest applicable unit (minute, hour, day, etc.).

HumanReadable.duration(5.seconds) // "5 seconds"
HumanReadable.duration(7.days) // "1 week"
HumanReadable.duration(544.hours) // "3 weeks"

Use HumanReadable.timeAgo(instant) to convert a kotlinx-datetime Instant into a human-readable string representing the time elapsed since that instant (e.g., "2 hours ago") or the time until that instant (e.g., "in 8 minutes").

HumanReadable.timeAgo(now - 134.minutes) // "2 hours ago"
HumanReadable.timeAgo(now + 8.minutes) // "in 8 minutes"

Use HumanReadable.number(number) to format numbers according to the current locale's grouping and decimal separators.

// 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"

Use HumanReadable.fileSize(bytes, decimals) to format a byte count into a human-readable string. The library uses base 1024 for calculations.

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

Use HumanReadable.distance(value, unit, decimals) to format distances.

Note: Numbers in DistanceUnit.Meter and DistanceUnit.Foot are always formatted with 0 decimals. The decimals parameter only affects larger units like kilometers and miles.

// 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) // "5,200 ft"
HumanReadable.distance(value = 5350, unit = DistanceUnit.Foot) // "1.0 mi"
HumanReadable.distance(value = 28512, unit = DistanceUnit.Foot, decimals = 2) // "5.40 mi"

Use HumanReadable.abbreviation(number, decimals) to convert large numbers into abbreviated forms (e.g., 3,000 to "3K").

HumanReadable.abbreviation(3_000) // "3K"
HumanReadable.abbreviation(500_000) // "500K"
HumanReadable.abbreviation(2_500_000, decimals = 1) // "2.5M"

The following languages are supported:

• Arabic (since 1.13.0)
• Czech
• Chinese (since 1.3.0)
• Dutch
• English (default)
• Finnish (since 1.7.0)
• French
• German
• Greek (since 1.11.0)
• Italian
• Indonesian
• Japanese (since 1.5.0)
• Kazakh (since 1.10.0)
• Korean (since 1.5.0)
• Polish (since 1.3.0)
• Portuguese (since 1.9.0)
• Russian
• Spanish
• Turkish
• Ukrainian
• Uzbek (since 1.4.0)
• Vietnamese (since 1.6.0)