humanize

Durations, byte sizes, relative times, ordinals and counted words for people to read. Pure - no capabilities.

ecko get github.com/ecko-lang/humanize
import humanize

Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.

Version 0.2.0 - source - MIT.


duration(ms)

The two largest non-zero units of a duration given in milliseconds.

Units are d, h, m and s; anything under a second is milliseconds, and zero is "0s". A negative duration renders as its magnitude, and a Float is truncated first.

errors: bug/bad_argument when ms is not a finite number.

humanize.duration(7505000)   # "2h 5m"
humanize.duration(250)       # "250ms"

size(bytes)

A byte count in 1024-based units with one decimal, a trailing .0 dropped.

Units run B, KB, MB, GB, TB, PB. A tie rounds to even (535808 is "523.2 KB"), and a value that rounds up to 1024 moves to the next unit (1048575 is "1 MB"). A negative count keeps its sign. A Float is truncated first.

errors: bug/bad_argument when bytes is not a finite number.

humanize.size(1468006)   # "1.4 MB"

relative(event, now)

Coarse relative time from now to event, both unix-millisecond timestamps.

A later now reads as the past ("3 days ago"), an earlier one as the future ("in 2 hours"), and within five seconds either way is "just now". Units run seconds, minutes, hours, days, months (30 days) and years (365 days). Pass time.now() as now; taking it as an argument keeps the result deterministic.

errors: bug/bad_argument when either timestamp is not a finite number.

humanize.relative(0, 259200000)   # "3 days ago"

ordinal(n)

The English ordinal of a whole number.

11, 12 and 13 take "th" despite ending in 1, 2 and 3, and a negative number takes the suffix of its magnitude (-1st), as the inflect package does. A Float is accepted only when it is whole (3.0).

errors: bug/bad_argument when n is not an Int or a whole Float.

humanize.ordinal(23)    # "23rd"
humanize.ordinal(-11)   # "-11th"

plural(n, singular, plural = null)

A count and a word, the word in the plural for anything but 1 or -1.

The plural follows the regular English endings (bus to buses, city to cities); pass it for anything irregular. A Float count is truncated first. The inflect package knows irregular words.

errors: bug/bad_argument when n is not a finite number or a word is not a string.

humanize.plural(3, "day")                # "3 days"
humanize.plural(2, "person", "people")   # "2 people"