humanize
Small Gleam helpers to make numbers, bytes, durations and lists human-friendly.
Quick API
| Function | Description |
|---|---|
humanize.number/1 | Compact numbers: 1_234 → "1.2K" |
humanize.number_with/3 | Control decimals and DecimalSeparator (Dot or Comma) |
humanize.bytes_decimal/1, humanize.bytes_binary/1 | File sizes (1000 vs 1024). Supports up to YB/YiB (decimal and binary, respectively). |
humanize.duration/1, humanize.duration_precise/1 | Human readable durations |
humanize.list/1, humanize.list_locale/3, humanize.list_with_oxford/1 | Natural language lists |
humanize.ordinal/1 | Ordinal suffixes (1st, 2nd, 3rd, …) |
humanize.time_ago_unix/5 | Humanize a Unix timestamp relative to now (locale-aware) |
humanize.time_ago_unix_with_overrides/6 | Same as above but accepts runtime locale overrides |
humanize.make_locale/6 | Construct a custom locale entry to pass as an override |
internals/locales.gleam | Internal table with built-in locales (it, en, es, fr, de, pt) |
Examples
import humanize
humanize.number(1_234) // "1.2K"
humanize.number_with(1_234_567, 2, humanize.Comma) // "1,23M"
humanize.bytes_decimal(1_536_000) // "1.5 MB"
// Large units
humanize.bytes_decimal(1_000_000_000_000_000) // "1 PB"
humanize.bytes_binary(1_125_899_906_842_624) // "1 PiB"
humanize.duration(125) // "2 minutes"
humanize.duration_precise(125) // "2 minutes, 5 seconds"
humanize.list(["a", "b", "c"]) // "a, b and c"
humanize.list_with_oxford(["a", "b", "c"]) // "a, b, and c"
humanize.list_with_ampersand(["a", "b", "c"]) // "a, b & c"
humanize.ordinal(23) // "23rd"
Time / i18n
import humanize
// Basic lookup using built-in locales
humanize.time_ago_unix(1_620_000_000, 1_620_000_360, "en", False, 1) // "6 minutes ago"
// For custom locale examples see the "Locale overrides" section below.
// Edge cases and behaviour near rounding boundaries
humanize.percent_with(12, 1, humanize.Dot, True) // "12.0 %"
humanize.number(999) // "999"
humanize.number(1000) // "1.0K"
humanize.number_with(999_950, 1, humanize.Dot) // promoted to "1.0M"
humanize.bytes_decimal(999) // "999 B"
humanize.bytes_decimal(1000) // "1 KB"
humanize.bytes_decimal(999_950) // promoted to "1.0 MB"
// Override example: future and precise
let my_units = [#(3600, "hX", "hX"), #(60, "minX", "minX"), #(1, "sX", "sX")]
let my_locale = humanize.make_locale("xx", "agoX", "inX", "nowX", " & ", my_units)
// future
humanize.time_ago_unix_with_overrides(1_000_120, 1_000_000, "xx", [my_locale], False, 1) // "inX 2 minX"
// precise
humanize.time_ago_unix_with_overrides(1_000_000 - { 3600 + 120 }, 1_000_000, "xx", [my_locale], True, 2) // "1 hX & 2 minX agoX"
Locale overrides
You can construct custom locale entries and pass them as overrides to time_ago_unix_with_overrides.
| Parameter | Type | Description |
|---|---|---|
code | String | Identifier code for the locale (e.g. it-roma). |
ago | String | Suffix for past tense (e.g. ago, fa). |
in_ | String | Prefix for future tense (e.g. in, tra). |
nowv | String | Text for the “now” case (e.g. now, adesso). |
conj | String | Conjunction used between units (e.g. and, e, &). |
units | List(#(Int, String, String)) | List of tuples (seconds, singular, plural), ordered from largest to smallest (years → months → … → seconds). |
The library helper is:
pub fn make_locale(
code: String,
ago: String,
in_: String,
nowv: String,
conj: String,
units: List(#(Int, String, String)),
) -> #(String, LocaleData)
Quick example:
let my_units = [#(3600, "ora_custom", "ore_custom"), #(60, "minuto_custom", "minuti_custom"), #(1, "secondo_custom", "secondi_custom")]
let my_locale = humanize.make_locale("it-roma", "fa", "tra", "adesso", " e ", my_units)
// Pass the override list to the call
humanize.time_ago_unix_with_overrides(past, now, "it-roma", [my_locale], False, 1)
Percent examples
| Example | Result |
|---|---|
humanize.percent(50) | "50%" |
humanize.percent_with(12, 1, humanize.Dot, False) | "12.0%" |
humanize.percent_ratio(1, 3, 2, humanize.Comma) | "33,33%" |
humanize.percent_ratio(1, 6, 1, humanize.Dot) | "16.7%" |
License
This project is available under the MIT License. See LICENSE.
Development
Run locally:
gleam run # Run the project
gleam test # Run the tests
Made with Gleam 💜