bytez

README

bytez

Package bytez provides functionality for working with large byte sizes and capacities in a human-friendly way in the belief that code and configuration files are more readable and less error-prone when they are specified with, for example, "4MiB" rather than "4194304".

The 'z' in the name is not an attempt to be cute but rather to create a package name that is short yet unique.

Documentation

Overview

bytez package encapsulates functionality for working with large byte sizes in a human-friendly way. (The 'z' in the name is not an attempt to be cute but to create a package name that is short yet unique.)

Unfortunately, the history is computing is one of inconsistency and ambiguity when it comes to specifying large byte sizes. For example, does 1KB mean 1000 bytes or 1024? It has been used to mean both. The unambiguous units KiB to indicate binary (powers of two) units were introduced in 1998 but are not universally used.

This package handles the ambiguity by using the letter case of the first letter of the units to determine the base: lowercase indicates base 10 and uppercase indicates base 2. (The "smaller" letter indicates the smaller units.) Thus, the following units all represent 4000 bytes: 4k, 4kb, 4kB. And the following units all represent 4096 bytes: 4K, 4KB, 4Kb, 4KiB

When converting from numbers to strings, this package uses the two-letter lowercase units (e.g. "mb") for powers of 10 and the three-letter mixed case (e.g. "MiB") for powers of 2.

Index

• Constants
• func AsInt(str string) (uint64, error)
• func AsStr(size uint64) string
• type Size
  • func (sz Size) MarshalText() ([]byte, error)
  • func (sz *Size) UnmarshalText(bytes []byte) error

Constants

const (
	Kilobyte uint64 = 1000
	Megabyte        = Kilobyte * 1000
	Gigabyte        = Megabyte * 1000
	Terabyte        = Gigabyte * 1000
	Petabyte        = Terabyte * 1000
	Exabyte         = Petabyte * 1000
)

Decimal (SI) constants that fit in 64 bits

const (
	Kibibyte uint64 = 1024
	Mebibyte        = Kibibyte * 1024
	Gibibyte        = Mebibyte * 1024
	Tebibyte        = Gibibyte * 1024
	Pebibyte        = Tebibyte * 1024
	Exbibyte        = Pebibyte * 1024
)

Binary (ISO/IEC) constants that fit in 64 bits

Functions

func AsInt

func AsInt(str string) (uint64, error)

AsInt accepts a byte size, like "4MiB", and returns the exact number of bytes, like 4194304. The leading number should be a whole number, but as a special case the fractions ".0" and ".5" are allowed, like "1.5mb" to indicate 1,500,000 bytes. A single space is allowed between the number and the units.

func AsStr

func AsStr(size uint64) string

AsStr accepts a number of bytes, like 4194304, and returns the byte size as a string, like "4MiB". The function tries to return a value that uses one of the supported units but it is not guaranteed to do so.

Types

type Size

type Size uint64

Type Size can be used to automatically marshal and unmarshal byte size specifications to and from text when parsing or outputting JSON, YAML, etc.

func (Size) MarshalText

func (sz Size) MarshalText() ([]byte, error)

func (*Size) UnmarshalText

func (sz *Size) UnmarshalText(bytes []byte) error