go-humanize converts technical numerical values and timestamps into human-readable formats. It provides utilities for formatting byte sizes (both decimal SI and binary IEC), humanizing time durations into relative expressions, adding thousand separators (commas) to numbers, converting integers to ordinal forms, formatting numbers with SI notation, and cleaning up float representations by removing trailing zeros.
go get github.com/dustin/go-humanizeimport "github.com/dustin/go-humanize"For English-specific utilities:
import "github.com/dustin/go-humanize/english"package main
import (
"fmt"
"time"
"github.com/dustin/go-humanize"
)
func main() {
// Format byte sizes
fmt.Println(humanize.Bytes(82854982)) // "83 MB"
fmt.Println(humanize.IBytes(82854982)) // "79 MiB"
// Add commas to numbers
fmt.Println(humanize.Comma(6582491)) // "6,582,491"
// Format ordinals
fmt.Println(humanize.Ordinal(3)) // "3rd"
// Relative time
past := time.Now().Add(-3 * time.Hour)
fmt.Println(humanize.Time(past)) // "3 hours ago"
// SI notation
fmt.Println(humanize.SI(0.00000000223, "M")) // "2.23 nM"
}Converts numeric byte values to human-readable strings (e.g., "83 MB", "79 MiB") and parses them back to numeric values. Supports both SI units (KB, MB, GB) and IEC units (KiB, MiB, GiB), with support for both uint64 and big.Int values.
// Format uint64 byte sizes
func Bytes(s uint64) string
func IBytes(s uint64) string
func ParseBytes(s string) (uint64, error)
// Format big.Int byte sizes
func BigBytes(s *big.Int) string
func BigIBytes(s *big.Int) string
func ParseBigBytes(s string) (*big.Int, error)Adds thousand separators (commas) to numbers and provides custom formatting options with configurable thousands and decimal separators.
// Add commas to numbers
func Comma(v int64) string
func Commaf(v float64) string
func CommafWithDigits(f float64, decimals int) string
func BigComma(b *big.Int) string
func BigCommaf(v *big.Float) string
// Float formatting without trailing zeros
func Ftoa(num float64) string
func FtoaWithDigits(num float64, digits int) string
// Custom number formatting
func FormatFloat(format string, n float64) string
func FormatInteger(format string, n int) stringConverts time.Time values into relative time expressions (e.g., "3 days ago", "2 weeks from now") with customizable labels and magnitude thresholds.
// Relative time formatting
func Time(then time.Time) string
func RelTime(a, b time.Time, albl, blbl string) string
func CustomRelTime(a, b time.Time, albl, blbl string, magnitudes []RelTimeMagnitude) string
// RelTimeMagnitude configures custom time magnitude formatting
type RelTimeMagnitude struct {
D time.Duration
Format string
DivBy time.Duration
}Formats numbers with scientific SI prefixes (p, n, µ, m, k, M, G, T, etc.) and parses SI notation strings back to numeric values.
// SI notation formatting
func SI(input float64, unit string) string
func SIWithDigits(input float64, decimals int, unit string) string
func ComputeSI(input float64) (float64, string)
func ParseSI(input string) (float64, string, error)Converts integers to ordinal strings with appropriate suffixes (1st, 2nd, 3rd, 4th, etc.).
func Ordinal(x int) stringProvides English-specific utilities for pluralization and formatting word lists with conjunctions and Oxford commas.
// Pluralization
func Plural(quantity int, singular, plural string) string
func PluralWord(quantity int, singular, plural string) string
// Word series formatting
func WordSeries(words []string, conjunction string) string
func OxfordWordSeries(words []string, conjunction string) stringThe package exports size and time constants for reference:
// IEC binary size constants (powers of 1024)
const (
Byte = 1 << (iota * 10)
KiByte
MiByte
GiByte
TiByte
PiByte
EiByte
)
// SI decimal size constants (powers of 1000)
const (
IByte = 1
KByte = IByte * 1000
MByte = KByte * 1000
GByte = MByte * 1000
TByte = GByte * 1000
PByte = TByte * 1000
EByte = PByte * 1000
)
// Time duration constants
const (
Day = 24 * time.Hour
Week = 7 * Day
Month = 30 * Day
Year = 12 * Month
LongTime = 37 * Year
)For working with very large byte sizes, the package provides big.Int variables:
// IEC binary size variables
var (
BigByte *big.Int
BigKiByte *big.Int
BigMiByte *big.Int
BigGiByte *big.Int
BigTiByte *big.Int
BigPiByte *big.Int
BigEiByte *big.Int
BigZiByte *big.Int
BigYiByte *big.Int
BigRiByte *big.Int
BigQiByte *big.Int
)
// SI decimal size variables
var (
BigSIByte *big.Int
BigKByte *big.Int
BigMByte *big.Int
BigGByte *big.Int
BigTByte *big.Int
BigPByte *big.Int
BigEByte *big.Int
BigZByte *big.Int
BigYByte *big.Int
BigRByte *big.Int
BigQByte *big.Int
)