humanize

A Kiwi package for converting raw data into human-readable strings.

Covers numbers, file sizes, durations, relative time, ordinals, pluralization, list formatting, truncation, percentages, and more.

---

Installation

zest install fuseraft/humanize

Then in your script:

include ".zest/load.kiwi"

---

Usage

humanize::number(n, sep = ",")

Formats a number with thousands separators.

humanize::number(1234567)        # "1,234,567"
humanize::number(1234567.89)     # "1,234,567.89"
humanize::number(-9876543)       # "-9,876,543"
humanize::number(1000, ".")      # "1.000"

---

humanize::compact(n, precision = 1)

Abbreviates a large number with a metric suffix (K, M, B, T).

humanize::compact(999)           # "999"
humanize::compact(1500)          # "1.5K"
humanize::compact(1500000)       # "1.5M"
humanize::compact(2300000000)    # "2.3B"
humanize::compact(4100000000000) # "4.1T"
humanize::compact(-42000)        # "-42.0K"
humanize::compact(1500, 0)       # "2K"

---

humanize::filesize(n_bytes, si = false)

Formats a byte count as a human-readable size. Uses binary units (KiB, MiB, ...) by default, or SI units (KB, MB, ...) when si is true.

humanize::filesize(0)              # "0 B"
humanize::filesize(512)            # "512 B"
humanize::filesize(1024)           # "1.0 KiB"
humanize::filesize(1048576)        # "1.0 MiB"
humanize::filesize(1073741824)     # "1.0 GiB"
humanize::filesize(1500000, true)  # "1.5 MB"

---

humanize::duration(seconds, short_form = false)

Formats a duration in seconds as a human-readable string.

humanize::duration(0)           # "0 seconds"
humanize::duration(1)           # "1 second"
humanize::duration(90)          # "1 minute, 30 seconds"
humanize::duration(3661)        # "1 hour, 1 minute, 1 second"
humanize::duration(86400)       # "1 day"
humanize::duration(90, true)    # "1m, 30s"
humanize::duration(-120)        # "-2 minutes"

---

humanize::duration_ms(ms, short_form = false)

Same as duration, but accepts milliseconds.

humanize::duration_ms(90000)         # "1 minute, 30 seconds"
humanize::duration_ms(90000, true)   # "1m, 30s"

---

humanize::time_ago(ts, now_ts = time::ticks())

Returns a relative time string from a Unix timestamp.

now = time::ticks()
humanize::time_ago(now - 5)          # "just now"
humanize::time_ago(now - 130)        # "2 minutes ago"
humanize::time_ago(now - 7200)       # "2 hours ago"
humanize::time_ago(now + 3600)       # "in 1 hour"

---

humanize::ordinal(n)

Returns the ordinal string for an integer.

humanize::ordinal(1)    # "1st"
humanize::ordinal(2)    # "2nd"
humanize::ordinal(3)    # "3rd"
humanize::ordinal(11)   # "11th"
humanize::ordinal(22)   # "22nd"
humanize::ordinal(101)  # "101st"

---

humanize::pluralize(n, word, plural = "")

Pluralizes a word based on a count. Handles common English irregulars automatically. Pass an explicit plural to override.

humanize::pluralize(1, "cat")            # "cat"
humanize::pluralize(2, "cat")            # "cats"
humanize::pluralize(2, "child")          # "children"
humanize::pluralize(2, "party")          # "parties"
humanize::pluralize(2, "match")          # "matches"
humanize::pluralize(3, "ox")             # "oxen"
humanize::pluralize(2, "cactus")         # "cacti"
humanize::pluralize(2, "person", "folk") # "folk"

---

humanize::listing(items, conjunction = "and", oxford = true)

Joins a list as a natural-language enumeration.

humanize::listing([])                              # ""
humanize::listing(["Alice"])                       # "Alice"
humanize::listing(["Alice", "Bob"])                # "Alice and Bob"
humanize::listing(["Alice", "Bob", "Charlie"])     # "Alice, Bob, and Charlie"
humanize::listing(["a", "b", "c"], "or")           # "a, b, or c"
humanize::listing(["a", "b", "c"], "and", false)   # "a, b and c"

---

humanize::truncate(s, max_len = 80, ellipsis = "...")

Truncates a string to a maximum length, appending an ellipsis if cut.

humanize::truncate("Hello, world!", 20)       # "Hello, world!"
humanize::truncate("Hello, world!", 8)        # "Hello..."
humanize::truncate("Hello, world!", 7, "…")   # "Hello, …"

---

humanize::wrap(s, width = 80)

Word-wraps a string to a given line width.

humanize::wrap("The quick brown fox jumped over the lazy dog", 20)
# "The quick brown fox\njumped over the\nlazy dog"

---

humanize::percent(ratio, precision = 1)

Formats a ratio (0.0–1.0) as a percentage string.

humanize::percent(0.0)        # "0.0%"
humanize::percent(0.753)      # "75.3%"
humanize::percent(1.0)        # "100.0%"
humanize::percent(0.5, 0)     # "50%"

---

humanize::titlecase(s)

Converts a string to title case.

humanize::titlecase("hello world")          # "Hello World"
humanize::titlecase("the quick brown fox")  # "The Quick Brown Fox"

---

humanize::slug(s)

Converts a string to a URL-friendly slug.

humanize::slug("Hello, World!")      # "hello-world"
humanize::slug("  foo  BAR  baz  ")  # "foo-bar-baz"
humanize::slug("C++ is #1!")         # "c-is-1"

---

humanize::pad_number(n, width = 2)

Pads a number with leading zeroes to a fixed width.

humanize::pad_number(7)      # "07"
humanize::pad_number(42)     # "42"
humanize::pad_number(7, 4)   # "0007"

---

humanize::decimal(n, places = 2)

Formats a number with a fixed number of decimal places.

humanize::decimal(3.1)          # "3.10"
humanize::decimal(3.14159, 3)   # "3.141"
humanize::decimal(42, 2)        # "42.00"

---

License

MIT