bytesize

package module
Version: v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 24, 2021 License: MIT Imports: 4 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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 added in v1.1.0

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 added in v1.1.0

type ParseError struct {
	Value string
	Err   error
}

An ParseError is an error parsing a byte size.

func (*ParseError) Error added in v1.1.0

func (e *ParseError) Error() string

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL