clj-commons/humanize

The intcomma function converts an integer to a string containing commas every three digits.

(require '[clj-commons.humanize :as h])

(h/intcomma 1000)
;; => "1,000"

(h/intcomma 1000000)
;; => "1,000,000"

The intword function converts large integers into a friendly text representation (e.g., 1.2 million). It is optimized for numbers over 1 million and supports up to decillion (33 digits) and googol (100 digits).

(require '[clj-commons.humanize :as h])

(h/intword 2000000000)
;; => "2.0 billion"

(h/intword 3500000000000000000000N)
;; => "3.5 sextillion"

The duration function converts a millisecond value into a human-readable string (e.g., "five minutes, twenty-five seconds"). You can pass a :number-format option to switch between word-based and digit-based numbers.

(require '[clj-commons.humanize :as h])

(h/duration 325100)
;; => "five minutes, twenty-five seconds"

(h/duration 325100 {:number-format str})
;; => "5 minutes, 25 seconds"

The truncate function shortens a string if it exceeds a specified length, appending a suffix (defaults to an ellipsis ...).

(require '[clj-commons.humanize :as h])

(h/truncate "abcdefghijklmnopqrstuvwxyz" 10)
;; => "abcdefg..."

(h/truncate "abcdefghijklmnopqrstuvwxyz" 10 "[more]")
;; => "abcd[more]"

The pluralize-noun function in the clj-commons.humanize.inflect namespace returns the pluralized version of a noun if the provided number is not 1.

(require '[clj-commons.humanize.inflect :as i])

(i/pluralize-noun 2 "thief")
;; => "thieves"

(i/pluralize-noun 5 "person")
;; => "people"

The relative-datetime function combines duration and datetime to describe a specific point in time relative to the current time. By default, the result is truncated to two adjacent terms.

Key options:

• :brief? true: Returns a condensed version (e.g., "3d 2h ago"). Requires a :list-format like h/space-list-format.
• :max-terms: Limits the number of time components returned.

(require '[clj-commons.humanize :as h])

(h/relative-datetime #inst "2026-03-23T19:52:36.129-00:00")
;; => "two hours, nineteen minutes ago"

(h/relative-datetime #inst "2026-03-20T19:52:36.129-00:00" :brief? true :list-format h/space-list-format)
;; => "3d 2h ago"

The numberword function takes a number and returns its full written string form (e.g., converting 3567 to "three thousand five hundred and sixty-seven").

(require '[clj-commons.humanize :as h])

(h/numberword 3567)
;; => "three thousand five hundred and sixty-seven"

(h/numberword 23237897)
;; => "twenty-three million two hundred and thirty-seven thousand eight hundred and ninety-seven"

The ordinal function converts an integer to its ordinal string representation (e.g., 1 becomes "1st").

(require '[clj-commons.humanize :as h])

(h/ordinal 1)
;; => "1st"

(h/ordinal 11)
;; => "11th"

The filesize function formats a number of bytes into a human-readable string.

• By default, it uses decimal suffixes (kB, MB).
• Set :binary true to use binary suffixes (KiB, MiB).
• Use the :format option to control the numeric part (e.g., "%.2f").

(require '[clj-commons.humanize :as h])

;; Decimal (default)
(h/filesize 3000000)
;; => "3.0MB"

;; Binary with custom format
(h/filesize 3000 :binary true :format "%.2f")
;; => "2.93KiB"

The datetime function takes a date or datetime object and returns a human-friendly string describing the time difference relative to the current time (e.g., "30 seconds ago" or "in 30 seconds").

(require '[clj-commons.humanize :as h])
(import '(java.time LocalDateTime) '(java.time.temporal ChronoUnit))

(h/datetime (.plusSeconds (LocalDateTime/now) -30))
;; => "30 seconds ago"

(h/datetime (.plus (LocalDateTime/now) -7 ChronoUnit/YEARS))
;; => "7 years ago"

The oxford function converts a list of items into a string using the Oxford comma style.

Key options:

• :maximum-display: Limits the number of items shown and uses a count for the rest (e.g., "and 2 others").
• :truncate-noun: Provides a noun to use when truncating (e.g., "2 other fruits").
• :number-format: Allows passing a function like h/numberword to format the count.

(require '[clj-commons.humanize :as h])

(h/oxford ["apple" "orange" "mango" "pear"] :maximum-display 2)
;; => "apple, orange, and 2 others"

(h/oxford ["apple" "orange" "mango" "pear"] 
          :maximum-display 2 
          :number-format h/numberword 
          :truncate-noun "fruit")
;; => "apple, orange, and two other fruits"