README

Humane Units Build Status GoDoc

Just a few functions for helping humanize times and sizes.

go get it as github.com/dustin/go-humanize, import it as "github.com/dustin/go-humanize", use it as humanize.

See godoc for complete documentation.

Sizes

This lets you take numbers like 82854982 and convert them to useful strings like, 83 MB or 79 MiB (whichever you prefer).

Example:

fmt.Printf("That file is %s.", humanize.Bytes(82854982)) // That file is 83 MB.

Times

This lets you take a time.Time and spit it out in relative terms. For example, 12 seconds ago or 3 days from now.

Example:

fmt.Printf("This was touched %s.", humanize.Time(someTimeInstance)) // This was touched 7 hours ago.

Thanks to Kyle Lemons for the time implementation from an IRC conversation one day. It's pretty neat.

Ordinals

From a mailing list discussion where a user wanted to be able to label ordinals.

0 -> 0th
1 -> 1st
2 -> 2nd
3 -> 3rd
4 -> 4th
[...]

Example:

fmt.Printf("You're my %s best friend.", humanize.Ordinal(193)) // You are my 193rd best friend.

Commas

Want to shove commas into numbers? Be my guest.

0 -> 0
100 -> 100
1000 -> 1,000
1000000000 -> 1,000,000,000
-100000 -> -100,000

Example:

fmt.Printf("You owe $%s.\n", humanize.Comma(6582491)) // You owe $6,582,491.

Ftoa

Nicer float64 formatter that removes trailing zeros.

fmt.Printf("%f", 2.24)                // 2.240000
fmt.Printf("%s", humanize.Ftoa(2.24)) // 2.24
fmt.Printf("%f", 2.0)                 // 2.000000
fmt.Printf("%s", humanize.Ftoa(2.0))  // 2

SI notation

Format numbers with SI notation.

Example:

humanize.SI(0.00000000223, "M") // 2.23 nM

English-specific functions

The following functions are in the humanize/english subpackage.

Plurals

Simple English pluralization

english.PluralWord(1, "object", "") // object
english.PluralWord(42, "object", "") // objects
english.PluralWord(2, "bus", "") // buses
english.PluralWord(99, "locus", "loci") // loci

english.Plural(1, "object", "") // 1 object
english.Plural(42, "object", "") // 42 objects
english.Plural(2, "bus", "") // 2 buses
english.Plural(99, "locus", "loci") // 99 loci
Word series

Format comma-separated words lists with conjuctions:

english.WordSeries([]string{"foo"}, "and") // foo
english.WordSeries([]string{"foo", "bar"}, "and") // foo and bar
english.WordSeries([]string{"foo", "bar", "baz"}, "and") // foo, bar and baz

english.OxfordWordSeries([]string{"foo", "bar", "baz"}, "and") // foo, bar, and baz
Expand ▾ Collapse ▴

Documentation

Overview

    Package humanize converts boring ugly numbers to human-friendly strings and back.

    Durations can be turned into strings such as "3 days ago", numbers representing sizes like 82854982 into useful strings like, "83 MB" or "79 MiB" (whichever you prefer).

    Index

    Constants

    View Source
    const (
    	Byte = 1 << (iota * 10)
    	KiByte
    	MiByte
    	GiByte
    	TiByte
    	PiByte
    	EiByte
    )

      IEC Sizes. kibis of bits

      View Source
      const (
      	IByte = 1
      	KByte = IByte * 1000
      	MByte = KByte * 1000
      	GByte = MByte * 1000
      	TByte = GByte * 1000
      	PByte = TByte * 1000
      	EByte = PByte * 1000
      )

        SI Sizes.

        View Source
        const (
        	Day      = 24 * time.Hour
        	Week     = 7 * Day
        	Month    = 30 * Day
        	Year     = 12 * Month
        	LongTime = 37 * Year
        )

          Seconds-based time units

          Variables

          View Source
          var (
          
          	// BigByte is one byte in bit.Ints
          	BigByte = big.NewInt(1)
          	// BigKiByte is 1,024 bytes in bit.Ints
          	BigKiByte = (&big.Int{}).Mul(BigByte, bigIECExp)
          	// BigMiByte is 1,024 k bytes in bit.Ints
          	BigMiByte = (&big.Int{}).Mul(BigKiByte, bigIECExp)
          	// BigGiByte is 1,024 m bytes in bit.Ints
          	BigGiByte = (&big.Int{}).Mul(BigMiByte, bigIECExp)
          	// BigTiByte is 1,024 g bytes in bit.Ints
          	BigTiByte = (&big.Int{}).Mul(BigGiByte, bigIECExp)
          	// BigPiByte is 1,024 t bytes in bit.Ints
          	BigPiByte = (&big.Int{}).Mul(BigTiByte, bigIECExp)
          	// BigEiByte is 1,024 p bytes in bit.Ints
          	BigEiByte = (&big.Int{}).Mul(BigPiByte, bigIECExp)
          	// BigZiByte is 1,024 e bytes in bit.Ints
          	BigZiByte = (&big.Int{}).Mul(BigEiByte, bigIECExp)
          	// BigYiByte is 1,024 z bytes in bit.Ints
          	BigYiByte = (&big.Int{}).Mul(BigZiByte, bigIECExp)
          )
          View Source
          var (
          
          	// BigSIByte is one SI byte in big.Ints
          	BigSIByte = big.NewInt(1)
          	// BigKByte is 1,000 SI bytes in big.Ints
          	BigKByte = (&big.Int{}).Mul(BigSIByte, bigSIExp)
          	// BigMByte is 1,000 SI k bytes in big.Ints
          	BigMByte = (&big.Int{}).Mul(BigKByte, bigSIExp)
          	// BigGByte is 1,000 SI m bytes in big.Ints
          	BigGByte = (&big.Int{}).Mul(BigMByte, bigSIExp)
          	// BigTByte is 1,000 SI g bytes in big.Ints
          	BigTByte = (&big.Int{}).Mul(BigGByte, bigSIExp)
          	// BigPByte is 1,000 SI t bytes in big.Ints
          	BigPByte = (&big.Int{}).Mul(BigTByte, bigSIExp)
          	// BigEByte is 1,000 SI p bytes in big.Ints
          	BigEByte = (&big.Int{}).Mul(BigPByte, bigSIExp)
          	// BigZByte is 1,000 SI e bytes in big.Ints
          	BigZByte = (&big.Int{}).Mul(BigEByte, bigSIExp)
          	// BigYByte is 1,000 SI z bytes in big.Ints
          	BigYByte = (&big.Int{}).Mul(BigZByte, bigSIExp)
          )

          Functions

          func BigBytes

          func BigBytes(s *big.Int) string

            BigBytes produces a human readable representation of an SI size.

            See also: ParseBigBytes.

            BigBytes(82854982) -> 83 MB

            func BigComma

            func BigComma(b *big.Int) string

              BigComma produces a string form of the given big.Int in base 10 with commas after every three orders of magnitude.

              func BigCommaf

              func BigCommaf(v *big.Float) string

                BigCommaf produces a string form of the given big.Float in base 10 with commas after every three orders of magnitude.

                func BigIBytes

                func BigIBytes(s *big.Int) string

                  BigIBytes produces a human readable representation of an IEC size.

                  See also: ParseBigBytes.

                  BigIBytes(82854982) -> 79 MiB

                  func Bytes

                  func Bytes(s uint64) string

                    Bytes produces a human readable representation of an SI size.

                    See also: ParseBytes.

                    Bytes(82854982) -> 83 MB

                    func Comma

                    func Comma(v int64) string

                      Comma produces a string form of the given number in base 10 with commas after every three orders of magnitude.

                      e.g. Comma(834142) -> 834,142

                      func Commaf

                      func Commaf(v float64) string

                        Commaf produces a string form of the given number in base 10 with commas after every three orders of magnitude.

                        e.g. Commaf(834142.32) -> 834,142.32

                        func CommafWithDigits

                        func CommafWithDigits(f float64, decimals int) string

                          CommafWithDigits works like the Commaf but limits the resulting string to the given number of decimal places.

                          e.g. CommafWithDigits(834142.32, 1) -> 834,142.3

                          func ComputeSI

                          func ComputeSI(input float64) (float64, string)

                            ComputeSI finds the most appropriate SI prefix for the given number and returns the prefix along with the value adjusted to be within that prefix.

                            See also: SI, ParseSI.

                            e.g. ComputeSI(2.2345e-12) -> (2.2345, "p")

                            func CustomRelTime

                            func CustomRelTime(a, b time.Time, albl, blbl string, magnitudes []RelTimeMagnitude) string

                              CustomRelTime formats a time into a relative string.

                              It takes two times two labels and a table of relative time formats. In addition to the generic time delta string (e.g. 5 minutes), the labels are used applied so that the label corresponding to the smaller time is applied.

                              func FormatFloat

                              func FormatFloat(format string, n float64) string

                                FormatFloat produces a formatted number as string based on the following user-specified criteria: * thousands separator * decimal separator * decimal precision

                                Usage: s := RenderFloat(format, n) The format parameter tells how to render the number n.

                                See examples: http://play.golang.org/p/LXc1Ddm1lJ

                                Examples of format strings, given n = 12345.6789: "#,###.##" => "12,345.67" "#,###." => "12,345" "#,###" => "12345,678" "#\u202F###,##" => "12 345,68" "#.###,###### => 12.345,678900 "" (aka default format) => 12,345.67

                                The highest precision allowed is 9 digits after the decimal symbol. There is also a version for integer number, FormatInteger(), which is convenient for calls within template.

                                func FormatInteger

                                func FormatInteger(format string, n int) string

                                  FormatInteger produces a formatted number as string. See FormatFloat.

                                  func Ftoa

                                  func Ftoa(num float64) string

                                    Ftoa converts a float to a string with no trailing zeros.

                                    func FtoaWithDigits

                                    func FtoaWithDigits(num float64, digits int) string

                                      FtoaWithDigits converts a float to a string but limits the resulting string to the given number of decimal places, and no trailing zeros.

                                      func IBytes

                                      func IBytes(s uint64) string

                                        IBytes produces a human readable representation of an IEC size.

                                        See also: ParseBytes.

                                        IBytes(82854982) -> 79 MiB

                                        func Ordinal

                                        func Ordinal(x int) string

                                          Ordinal gives you the input number in a rank/ordinal format.

                                          Ordinal(3) -> 3rd

                                          func ParseBigBytes

                                          func ParseBigBytes(s string) (*big.Int, error)

                                            ParseBigBytes parses a string representation of bytes into the number of bytes it represents.

                                            See also: BigBytes, BigIBytes.

                                            ParseBigBytes("42 MB") -> 42000000, nil ParseBigBytes("42 mib") -> 44040192, nil

                                            func ParseBytes

                                            func ParseBytes(s string) (uint64, error)

                                              ParseBytes parses a string representation of bytes into the number of bytes it represents.

                                              See Also: Bytes, IBytes.

                                              ParseBytes("42 MB") -> 42000000, nil ParseBytes("42 mib") -> 44040192, nil

                                              func ParseSI

                                              func ParseSI(input string) (float64, string, error)

                                                ParseSI parses an SI string back into the number and unit.

                                                See also: SI, ComputeSI.

                                                e.g. ParseSI("2.2345 pF") -> (2.2345e-12, "F", nil)

                                                func RelTime

                                                func RelTime(a, b time.Time, albl, blbl string) string

                                                  RelTime formats a time into a relative string.

                                                  It takes two times and two labels. In addition to the generic time delta string (e.g. 5 minutes), the labels are used applied so that the label corresponding to the smaller time is applied.

                                                  RelTime(timeInPast, timeInFuture, "earlier", "later") -> "3 weeks earlier"

                                                  func SI

                                                  func SI(input float64, unit string) string

                                                    SI returns a string with default formatting.

                                                    SI uses Ftoa to format float value, removing trailing zeros.

                                                    See also: ComputeSI, ParseSI.

                                                    e.g. SI(1000000, "B") -> 1 MB e.g. SI(2.2345e-12, "F") -> 2.2345 pF

                                                    func SIWithDigits

                                                    func SIWithDigits(input float64, decimals int, unit string) string

                                                      SIWithDigits works like SI but limits the resulting string to the given number of decimal places.

                                                      e.g. SIWithDigits(1000000, 0, "B") -> 1 MB e.g. SIWithDigits(2.2345e-12, 2, "F") -> 2.23 pF

                                                      func Time

                                                      func Time(then time.Time) string

                                                        Time formats a time into a relative string.

                                                        Time(someT) -> "3 weeks ago"

                                                        Types

                                                        type RelTimeMagnitude

                                                        type RelTimeMagnitude struct {
                                                        	D      time.Duration
                                                        	Format string
                                                        	DivBy  time.Duration
                                                        }

                                                          A RelTimeMagnitude struct contains a relative time point at which the relative format of time will switch to a new format string. A slice of these in ascending order by their "D" field is passed to CustomRelTime to format durations.

                                                          The Format field is a string that may contain a "%s" which will be replaced with the appropriate signed label (e.g. "ago" or "from now") and a "%d" that will be replaced by the quantity.

                                                          The DivBy field is the amount of time the time difference must be divided by in order to display correctly.

                                                          e.g. if D is 2*time.Minute and you want to display "%d minutes %s" DivBy should be time.Minute so whatever the duration is will be expressed in minutes.

                                                          Directories

                                                          Path Synopsis
                                                          Package english provides utilities to generate more user-friendly English output.
                                                          Package english provides utilities to generate more user-friendly English output.