package module
Version: v0.0.0-...-859f65c Latest Latest

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

Go to latest
Published: Jun 6, 2022 License: MIT Imports: 4 Imported by: 261


datasize Build Status

Golang helpers for data sizes


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

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.Petebytes() float64
  • ByteSize.Exabytes() float64

Warning: see limitations at the end of this document about a possible precission 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"))

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"
  • 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




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


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


This section is empty.


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

Source Files

Jump to

Keyboard shortcuts

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