bytesize

README

ByteSize

Simple and correct.

ByteSize is a library for formatting and parsing numbers as byte sizes for humans. Numbers are formatted with three digits of precision, using SI prefixes, and the unit "B" for bytes. For example, 1000 is formatted as "1.00 KB". The numbers are rounded using round-to-even, which is the familiar method used by fmt.Sprintf, math.Round, and other functions in the standard library.

There are no choices to make. ByteSize is not configurable.

Formatting

The precision cannot be changed. Non-decimal prefixes are not produced: no kibibytes, no powers of two. There is only one function to call.

func Format(size uint64) string

All corner cases should be handled correctly and you should never see unusual or unexpected output. You should always see exactly three digits, except for inputs under 100.

Some test cases:

0 => "0 B"
999 => "999 B"
1000 => "1.00 kB"
1005 => "1.00 kB"
1006 => "1.01 kB"
1014 => "1.01 kB"
1015 => "1.02 kB"
9995 => "10.0 kB"
314000 => "314 kB"
18400000000000000 => "18.4 PB"

Parsing

The parser understands decimal numbers, decimal SI prefixes, and binary SI prefixes. It is not case-sensitive. ASCII space (0x20) may appear between the number and the units. This will recognize all positve prefixes which are powers of 1,000, including prefixes that will overflow (yotta and zetta).

func Parse(s string) (uint64, error)

Some test cases:

"0" => 0
"1" => 1
"555k" => 555000
"15 EiB" => 17293822569102704640
"1.5 mb" => 1500000
"2gi" => 2147483648
"0.001 zb" => 1000000000000000000

On overflow, this will return ^uint64(0) and a ParseError containing ErrRange.

License

This is licensed under the MIT license. See LICENSE.txt.

Documentation

Overview

Package bytesize formats data sizes as strings.

Index

• Variables
• func Format(size uint64) string
• func Parse(s string) (uint64, error)
• type ParseError
  • func (e *ParseError) Error() string

Variables

var (

	// ErrRange indicates that the byte size is too large to fit in a uint64.
	ErrRange = errors.New("byte size out of range")
)

Functions

func Format

func Format(size uint64) string

Format formats a data size for humans. The size is rounded to three significant digits, but never more than integer accuracy, and printed with SI prefixes, with the unit B for bytes.

For example, 1000 is formatted as "1.00 kB".

This uses unbiased, round-to-even rounding just like the standard library does (math.Round, strconv.FormatFloat). So 1005 is "1.00 kB", and 1015 is "1.02 kB".

func Parse

func Parse(s string) (uint64, error)

Parse parses a string as a byte size, which may contain units and may use a decimal point. If the result would overflow a uint64, returns a ParseError with an ErrRange inside. Results are rounded to even, although results for binary prefixes may not be exactly rounded. The units are the standard SI units as well as their binary counterparts, optionally followed by "b". ASCII space characters may appear between the number and the units.

Parse("1") = 1
Parse("555k") = 555000
Parse("15 EiB") = 17293822569102704640
Parse("1.5 mb") = 1500000
Parse("2gi") = 2147483648
Parse("0.001 zb") = 1000000000000000000

Types

type ParseError

type ParseError struct {
	Value string
	Err   error
}

An ParseError is an error parsing a byte size.

func (*ParseError) Error

func (e *ParseError) Error() string