or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

byte-sizes.mdenglish.mdindex.mdnumber-formatting.mdordinals.mdsi-notation.mdtime-formatting.md
tile.json

tessl/golang-github-com-dustin--go-humanize

Humane Units - functions for helping humanize times and sizes

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/github.com/dustin/go-humanize@v1.0.1

To install, run

npx @tessl/cli install tessl/golang-github-com-dustin--go-humanize@1.0.0

index.mddocs/

go-humanize

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.

Package Information

  • Package Name: github.com/dustin/go-humanize
  • Package Type: golang
  • Language: Go
  • Version: 1.0.1
  • Installation: go get github.com/dustin/go-humanize
  • License: MIT

Core Imports

import "github.com/dustin/go-humanize"

For English-specific utilities:

import "github.com/dustin/go-humanize/english"

Basic Usage

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"
}

Capabilities

Byte Size Formatting

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)

Byte Size Formatting

Number Formatting

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) string

Number Formatting

Time Formatting

Converts 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
}

Time Formatting

SI Notation

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)

SI Notation

Ordinal Numbers

Converts integers to ordinal strings with appropriate suffixes (1st, 2nd, 3rd, 4th, etc.).

func Ordinal(x int) string

Ordinals

English Language Utilities

Provides 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) string

English Utilities

Constants

The 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
)

Big.Int Size Variables

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
)