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.

Installation

Download and install module with:

go get github.com/codexnull/bytez

Usage

To use, simply

import github.com/codexnull/bytez

in your code.

Then, sizes can be specified using constants. For example, the code

bufSize := 16*bytez.Kibibyte
buffer := make([]byte, bufSize)
fmt.Printf("Buffer Size: %v (%v)\n", len(buffer), bytez.AsStr(bufSize))

outputs

Buffer Size: 16384 (16KiB)

The functions bytez.AsStr() and bytez.AsInt() can be used to convert to and from size specifications and number of bytes. For example, if bufSize is 16384, bytez.AsStr(bufSize) will return "16KiB". And if cacheSize is "8MiB", bytez.AsInt(cacheSize) will return 8388608.

The package also provides a Size type that supports marshaling to and from text using the functions above when marshaling to and from JSON, YAML, etc. So the code

type Conf struct {
    ...
    CacheSize bytez.Size `json:"cache_size"`
    ...
}
conf := Conf{CacheSize: bytez.Size(2 * bytez.Gibibyte)}

Will result in

{
  ...
  "cache_size":"2GiB",
  ...
}

when conf is marshaled to JSON. Unmarshaling will result in the value 2 * bytez.Gibibyte back.

See the godoc for details.

Documentation

Overview

Package bytez 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

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)

MarshalText implements the encoding.TextMarshaler interface. The size is formatted as a string using the largest units possible. Returned error is always nil.

func (*Size) UnmarshalText

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

UnmarshalText implements the encoding.TextUnmarshaler interface.