datasize

README

datasize

Golang helpers for data sizes

Constants

Just like time package provides time.Second, time.Day constants datasize provides:

• datasize.B 1 byte
• datasize.KB 1 kilobyte
• datasize.MB 1 megabyte
• datasize.GB 1 gigabyte
• datasize.TB 1 terabyte
• datasize.PB 1 petabyte
• datasize.EB 1 exabyte

Helpers

Just like time package provides duration.Nanoseconds() uint64 , duration.Hours() float64 helpers datasize has.

• ByteSize.Bytes() uint64
• ByteSize.Kilobytes() float64
• ByteSize.Megabytes() float64
• ByteSize.Gigabytes() float64
• ByteSize.Terabytes() float64
• ByteSize.Petabytes() float64
• ByteSize.Exabytes() float64

Warning: see limitations at the end of this document about a possible precision loss

Parsing strings

datasize.ByteSize implements TextUnmarshaler interface and will automatically parse human readable strings into correct values where it is used:

• "10 MB" -> 10* datasize.MB
• "10240 g" -> 10 * datasize.TB
• "2000" -> 2000 * datasize.B
• "1tB" -> datasize.TB
• "5 peta" -> 5 * datasize.PB
• "28 kilobytes" -> 28 * datasize.KB
• "1 gigabyte" -> 1 * datasize.GB

You can also do it manually:

var v datasize.ByteSize
err := v.UnmarshalText([]byte("100 mb"))

Printing

Bytesize.String() uses largest unit allowing an integer value:

• (102400 * datasize.MB).String() -> "100GB"
• (datasize.MB + datasize.KB).String() -> "1025KB"

Use %d format string to get value in bytes without a unit.

JSON and other encoding

Both TextMarshaler and TextUnmarshaler interfaces are implemented - JSON will just work. Other encoders will work provided they use those interfaces.

Human readable

ByteSize.HumanReadable() or ByteSize.HR() returns a string with 1-3 digits, followed by 1 decimal place, a space and unit big enough to get 1-3 digits

• (102400 * datasize.MB).String() -> "100.0 GB"
• (datasize.MB + 512 * datasize.KB).String() -> "1.5 MB"

Limitations

• The underlying data type for data.ByteSize is uint64, so values outside of 0 to 2^64-1 range will overflow
• size helper functions (like ByteSize.Kilobytes()) return float64, which can't represent all possible values of uint64 accurately:
  • if the returned value is supposed to have no fraction (ie (10 * datasize.MB).Kilobytes()) accuracy loss happens when value is more than 2^53 larger than unit: .Kilobytes() over 8 petabytes, .Megabytes() over 8 exabytes
  • if the returned value is supposed to have a fraction (ie (datasize.PB + datasize.B).Megabytes()) in addition to the above note accuracy loss may occur in fractional part too - larger integer part leaves fewer bytes to store fractional part, the smaller the remainder vs unit the move bytes are required to store the fractional part
• Parsing a string with Mb, Tb, etc units will return a syntax error, because capital followed by lower case is commonly used for bits, not bytes
• Parsing a string with value exceeding 2^64-1 bytes will return 2^64-1 and an out of range error

Documentation

Index

• Constants
• Variables
• type ByteSize
  • func MustParse(t []byte) ByteSize
  • func MustParseString(s string) ByteSize
  • func Parse(t []byte) (ByteSize, error)
  • func ParseString(s string) (ByteSize, error)
  • func (b ByteSize) Bytes() uint64
  • func (b ByteSize) EBytes() float64
  • func (b ByteSize) GBytes() float64
  • func (b ByteSize) HR() string
  • func (b ByteSize) HumanReadable() string
  • func (b ByteSize) KBytes() float64
  • func (b ByteSize) MBytes() float64
  • func (b ByteSize) MarshalText() ([]byte, error)
  • func (b ByteSize) PBytes() float64
  • func (b ByteSize) String() string
  • func (b ByteSize) TBytes() float64
  • func (b *ByteSize) UnmarshalText(t []byte) error

Constants

const (
	B  ByteSize = 1
	KB          = B << 10
	MB          = KB << 10
	GB          = MB << 10
	TB          = GB << 10
	PB          = TB << 10
	EB          = PB << 10
)

Variables

var ErrBits = errors.New("unit with capital unit prefix and lower case unit (b) - bits, not bytes ")

Types

type ByteSize

type ByteSize uint64

func MustParse

func MustParse(t []byte) ByteSize

func MustParseString

func MustParseString(s string) ByteSize

func Parse

func Parse(t []byte) (ByteSize, error)

func ParseString

func ParseString(s string) (ByteSize, error)

func (ByteSize) Bytes

func (b ByteSize) Bytes() uint64

func (ByteSize) EBytes

func (b ByteSize) EBytes() float64

func (ByteSize) GBytes

func (b ByteSize) GBytes() float64

func (ByteSize) HR

func (b ByteSize) HR() string

func (ByteSize) HumanReadable

func (b ByteSize) HumanReadable() string

func (ByteSize) KBytes

func (b ByteSize) KBytes() float64

func (ByteSize) MBytes

func (b ByteSize) MBytes() float64

func (ByteSize) MarshalText

func (b ByteSize) MarshalText() ([]byte, error)

func (ByteSize) PBytes

func (b ByteSize) PBytes() float64

func (ByteSize) String

func (b ByteSize) String() string

func (ByteSize) TBytes

func (b ByteSize) TBytes() float64

func (*ByteSize) UnmarshalText

func (b *ByteSize) UnmarshalText(t []byte) error