README
¶
Humanize
Humanize is a Go package that formats large numbers into human readable small numbers.
It's based on BSD's humanize_number(3) function in libutil.
Online package documentation is available via https://godoc.org/bitbucket.org/dchapes/humanize.
To install:
go get bitbucket.org/dchapes/humanize
or go build any Go code that imports it:
import "bitbucket.org/dchapes/humanize"
Documentation
¶
Overview ¶
Package humanize formats large numbers into human readable small numbers.
For example:
Using the default base 2:
9223372036854775807 as one of 9007199254740992k, 8796093022208M,
8589934592G, 8388608T, 8192P,
8.0E, or 8E
With SI prefixes:
9223372036854775807 as one of 9007199254740992Ki, 8796093022208Mi,
8589934592Gi, 8388608Ti, 8192Pi,
8.0Ei, or 8Ei
Using base 10 prefixes:
9223372036854775807 as one of 9223372036854776K, 9223372036855M,
9223372037G, 9223372T, 9223P,
9.2E, or 9E
Example ¶
package main
import (
"fmt"
"math"
"bitbucket.org/dchapes/humanize"
)
func main() {
var m int64 = math.MaxInt64
h := humanize.Int64(m)
fmt.Printf("Using the default base 2:\n %d\t", m)
for p := 16; p >= 4; p -= 3 {
fmt.Printf("≅ %.*v\n\t\t\t", p, h)
}
str := humanize.Format(m, 0, 4, humanize.NoSpace)
fmt.Printf("≅ %s\n\n", str)
fmt.Printf("With a space, SI prefixes, and a unit:\n %d\t", m)
for p := 18; p >= 4; p -= 3 {
fmt.Printf("≅ %#.*sB/s\n\t\t\t", p, h)
}
str = humanize.Format(m, 0, 4, humanize.SIPrefixes)
fmt.Printf("≅ %sB/s\n\n", str)
fmt.Printf("With base 10 prefixes:\n %d\t", m)
for p := 16; p >= 4; p = p - 3 {
fmt.Printf("≅ %.*d\n\t\t\t", p, h)
}
str = humanize.Format(m, 0, 4, humanize.NoSpace|humanize.Divisor1000)
fmt.Printf("≅ %s\n", str)
}
Output: Using the default base 2: 9223372036854775807 ≅ 8796093022208M ≅ 8589934592G ≅ 8388608T ≅ 8192P ≅ 8.0E ≅ 8E With a space, SI prefixes, and a unit: 9223372036854775807 ≅ 8796093022208 MiB/s ≅ 8589934592 GiB/s ≅ 8388608 TiB/s ≅ 8192 PiB/s ≅ 8.0 EiB/s ≅ 8 EiB/s With base 10 prefixes: 9223372036854775807 ≅ 9223372036855M ≅ 9223372037G ≅ 9223372T ≅ 9223P ≅ 9.2E ≅ 9E
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( DefaultMinLen = 0 DefaultMaxLen = 4 DefaultFlags = NoSpace | Decimal )
Defaults used by Itoa, Int64.String, and Int64.Format.
Functions ¶
func Format ¶
Format formats a value into a human readable form.
The value is divided and rounded until it will fit into into a string of the specified max length. If the number has been divided, a space and an appropriate unit prefix is also added (which also must fit into the specified max length). The NoSpace flag omits the space before the prefix (if any). If the resulting string is shorter than the min length specified, it will be padded.
By default, the traditional computer science conventions of dividing by 1024 and using the prefixes k, M, G, etc is used rather than the SI (and IEE/IEC) power of two convention (Ki, Mi, Gi, etc) or the power of ten notion (K, M, G, etc). The SIPrefixes and Divisor1000 flags change this behaviour.
The Decimal flag causes values <= 9.9 (after dividing and rounding) to be formated with a decimal and a single fractional digit (e.g. "1.2 G" instead of "1 G" when "1200 M" is too wide).
The maxlen argument must be at least 3 for positive values, and at least 4 for negative values. When SIPrefixes is specified the minimums are 4 and 5. Format will panic when maxlen is not adequate.
The traditional (default) prefixes:
Scale Prefix Description Multiplier Multiplier (Divisor1000) 0 /B¹ 1 1 1 k/K² kilo 1024 1000 2 M mega 1048576 1000000 3 G giga 1073741824 1000000000 4 T tera 1099511627776 1000000000000 5 P peta 1125899906842624 1000000000000000 6 E exa 1152921504606846976 1000000000000000000 ¹ B is used with the Bytes flag ² K is used with the Divisor1000 flag
The SI (and IEE/IEC) power of two prefixes:
Scale Prefix Description Multiplier 0 /B³ 1 1 Ki kibi 1024 2 Mi mebi 1048576 3 Gi gibi 1073741824 4 Ti tebi 1099511627776 5 Pi pebi 1125899906842624 6 Ei exbi 1152921504606846976 ³ B is used with the Bytes flag
func FormatToScale ¶
FormatToScale formats a value into a human readable form using a specific scale and prefix.
The prefixes and flags are as specified with the Format function.
func Scale ¶
Scale returns the scale that would be used to format the value using Format(value, 0, maxlen, flags).
One use of Scale is to store the maximum returned scale when called with a sequence of values and then call FormatToScale with that maxiumum for each value to have a column of values formatted to the same scale.
Types ¶
type Flags ¶
type Flags int
Flags specify the formating behaviour.
const ( Decimal Flags = 1 << iota // If the final result is less than 10, display it using one decimal point. NoSpace // Do not put a space between number and the prefix. Bytes // Use ‘B’ (bytes) as prefix if the original result does not have a prefix. Divisor1000 // Divide by 1000 instead of 1024. SIPrefixes // Use Ki, Mi, Gi, etc when dividing by 1024 AlwaysSign // Always include the sign ('+' or '-') SpaceSign // Leave a space for elided sign ZeroPad // Pad with leading zeros rather than spaces LeftJustify // Pad with spaces on the right rather than the left )
Flag values.
type Int64 ¶
type Int64 int64
Int64 is a plain int64 but with a humanized implemtation of fmt.Formatter and fmt.Stringer.
When used with printf style formating the following 'verbs' are supported and act as if the corresponding Flags are set:
%v DefaultFlags %T a Go-syntax representation of the type of the value %d Decimal | Divisor1000 | NoSpace %b Decimal | Bytes | NoSpace %s Decimal | SIPrefixes | NoSpace %#v DefaultFlags & ^NoSpace %#d Decimal | Divisor1000 %#b Decimal | Bytes %#s Decimal | SIPrefixes
If a width is specified, it is used to specify the minimum string length and the output will be padded as required. If a precision is specified it is used to limit the string length. If a width is specified without a precision, the precision (the string limit) is taken to be the width. If neither a width or precision is specified they default to DefaultMinLen (0, no padding) and DefaultMaxLen (4).
Other flags:
'+' always print the sign ('+' or '-')
' ' (space) leave a space for elided sign (' ' or '-')
'-' pad with spaces on the right rather than the left (left-justify the field)
'0' pad with leading zeros rather than spaces
'#' alternate format: put a space between the number and the prefix
Example ¶
package main
import (
"fmt"
"bitbucket.org/dchapes/humanize"
)
func main() {
h1 := humanize.Int64(750 * 1024)
h2 := humanize.Int64(1280 * 1024)
fmt.Printf("'%v'\n", humanize.Int64(42))
fmt.Printf("'%v' '%v'\n", h1, h2)
fmt.Printf("'%5v'\n", h2)
fmt.Printf("'%3v'\n", h2)
fmt.Printf("'%.6d'\n", h2)
fmt.Printf("'%#.8sB'\n", h2)
fmt.Printf("'%-7.4d'\n", h2)
fmt.Printf("'% -7.5d'\n", h2)
fmt.Printf("'%-+7.5d'\n", h2)
}
Output: '42' '750k' '1.3M' '1280k' ' 1M' '1311K' '1280 KiB' '1.3M ' ' 1.3M ' '+1.3M '
const ( Kilo Int64 // k or Ki (Note, K is used with Divisor1000) Mega // M or Mi Giga // G or Gi Tera // T or Ti Peta // P or Pi Exa // E or Ei MaxScale = iota )
Base 2 prefix values (e.g. Mega = 1024*1024)
func Parse ¶
Parse parses a formated number string. A formated number string is a possibly signed number with optional unit prefix.
The comibination of the flags argument plus the unit in the number string determine if the units are base2 or base10 (1024 or 1000 multipliers). If the unit is an SI prefix such as Ki, Mi, etc (lower case also accepted) then base2 multipliers are used without reguard to the flags argument. If the flags argument contains either the Divisor1000 or SIPrefixes flag then base10 multipliers are used, otherwise base2 multipliers are used.
Example ¶
package main
import (
"fmt"
"bitbucket.org/dchapes/humanize"
)
var any humanize.Flags
func main() {
a, _ := humanize.Parse("0.5 k", 0) // default *1024
b, _ := humanize.Parse("1.5K", humanize.Divisor1000) // changed with flag to *1000
c, _ := humanize.Parse(".5 Ki", any) // but input with SI always forces *1024
fmt.Println(int64(a))
fmt.Println(int64(b))
fmt.Println(int64(c))
}
Output: 512 1500 512
Source Files