README
¶
Humane Units 
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
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
- Variables
- func BigBytes(s *big.Int) string
- func BigComma(b *big.Int) string
- func BigCommaf(v *big.Float) string
- func BigIBytes(s *big.Int) string
- func Bytes(s uint64) string
- func BytesCustomCeil(s uint64, precision int) string
- func BytesCustomFloor(s uint64, precision int) string
- func Comma(v int64) string
- func Commaf(v float64) string
- func CommafWithDigits(f float64, decimals int) string
- func ComputeSI(input float64) (float64, string)
- func CustomRelTime(a, b time.Time, albl, blbl string, magnitudes []RelTimeMagnitude) string
- func FormatFloat(format string, n float64) string
- func FormatInteger(format string, n int) string
- func Ftoa(num float64) string
- func FtoaWithDigits(num float64, digits int) string
- func IBytes(s uint64) string
- func IBytesCustomCeil(s uint64, precision int) string
- func IBytesCustomFloor(s uint64, precision int) string
- func Ordinal(x int) string
- func ParseBigBytes(s string) (*big.Int, error)
- func ParseBytes(s string) (uint64, error)
- func ParseSI(input string) (float64, string, error)
- func RelTime(a, b time.Time, albl, blbl string) string
- func SI(input float64, unit string) string
- func SIWithDigits(input float64, decimals int, unit string) string
- func Time(then time.Time) string
- type RelTimeMagnitude
Constants ¶
const ( Byte = 1 << (iota * 10) KiByte MiByte GiByte TiByte PiByte EiByte )
IEC Sizes. kibis of bits
const ( IByte = 1 KByte = IByte * 1000 MByte = KByte * 1000 GByte = MByte * 1000 TByte = GByte * 1000 PByte = TByte * 1000 EByte = PByte * 1000 )
SI Sizes.
const ( Day = 24 * time.Hour Week = 7 * Day Month = 30 * Day Year = 12 * Month LongTime = 37 * Year )
Seconds-based time units
Variables ¶
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) )
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 ¶
BigBytes produces a human readable representation of an SI size.
See also: ParseBigBytes.
BigBytes(82854982) -> 83 MB
func BigComma ¶
BigComma produces a string form of the given big.Int in base 10 with commas after every three orders of magnitude.
func BigCommaf ¶
BigCommaf produces a string form of the given big.Float in base 10 with commas after every three orders of magnitude.
func BigIBytes ¶
BigIBytes produces a human readable representation of an IEC size.
See also: ParseBigBytes.
BigIBytes(82854982) -> 79 MiB
func Bytes ¶
Bytes produces a human readable representation of an SI size.
See also: ParseBytes.
Bytes(82854982) -> 83 MB
func BytesCustomCeil ¶
BytesCustomCeil allow to set precision and to get more or equal value with rounding
BytesCustomCeil(92160871366656, 2) -> 92.17 TB
func BytesCustomFloor ¶
BytesCustomFloor allow to set precision and to get less or equal value with rounding
BytesCustomFloor(92160871366656, 2) -> 92.16 TB
func Comma ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
FormatInteger produces a formatted number as string. See FormatFloat.
func FtoaWithDigits ¶
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 ¶
IBytes produces a human readable representation of an IEC size.
See also: ParseBytes.
IBytes(82854982) -> 79 MiB
func IBytesCustomCeil ¶
IBytesCustomCeil allow to set precision and to get more or equal value with rounding
IBytesCustomCeil(92160871366656, 2) -> 83.82 TiB
func IBytesCustomFloor ¶
IBytesCustomFloor allow to set precision and to get less or equal value with rounding
IBytesCustomFloor(92160871366656, 2) -> 83.81 TiB IBytesCustomFloor(92160871366656, 3) -> 83.8198242187
func ParseBigBytes ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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
Types ¶
type RelTimeMagnitude ¶
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.
Source Files
Directories