man

README

Humane Units

forked from https://github.com/dustin/go-humanize

Just a few functions for helping human times and sizes.

go get it as github.com/bingoohuang/gg/pkg/human, import it as "github.com/bingoohuang/gg/pkg/human", use it as human.

See godoc for complete documentation.

Sizes

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

Example:

fmt.Printf("That file is %s.", man.Bytes(82854982)) // That file is 82.9MB.
fmt.Printf("That file is %s.", man.IBytes(82854982)) // That file is 79MiB.

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.", man.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.", man.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", man.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", man.Ftoa(2.24)) // 2.24
fmt.Printf("%f", 2.0)                 // 2.000000
fmt.Printf("%s", man.Ftoa(2.0))  // 2

SI notation

Format numbers with SI notation.

Example:

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

English-specific functions

The following functions are in the human/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

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 ByteCount(b int64) string
• func Bytes(s uint64) 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 IByteCount(b int64) string
• func IBytes(s uint64) 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

Examples

• Bytes

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

func BigBytes(s *big.Int) string

BigBytes produces a human readable representation of an SI size.

See also: ParseBigBytes.

BigBytes(82854982) -> 83MB

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) -> 79MiB

func ByteCount

func ByteCount(b int64) string

ByteCount produces a human readable representation of an SI size（copy go version).

func Bytes

func Bytes(s uint64) string

Bytes produces a human readable representation of an SI size.

See also: ParseBytes.

Bytes(82854982) -> 83MB

Example

package main

import (
	"fmt"

	"github.com/bingoohuang/gg/pkg/man"
)

func main() {
	fmt.Printf("That file is %s.\n", man.Bytes(82854982))
	fmt.Printf("That file is %s.\n", man.IBytes(82854982))
	fmt.Printf("That file is %s.\n", man.ByteCount(82854982))
	fmt.Printf("That file is %s.\n", man.IByteCount(82854982))

}

Output:

That file is 82.9MB.
That file is 79MiB.
That file is 82.9MB.
That file is 79MiB.

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 IByteCount

func IByteCount(b int64) string

IByteCount produces a human readable representation of an IEC size（copy go version).

func IBytes

func IBytes(s uint64) string

IBytes produces a human readable representation of an IEC size.

See also: ParseBytes.

IBytes(82854982) -> 79MiB

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.