bytes

Documentation

Overview

Package bytes implements functionality for working with byte sizes.

The central type is Capacity, a uint64 count of bytes that knows how to render itself in the "human" form common Linux tools use ("10.4G") and how to parse that form back ("10G", "512Mi"). Capacity implements flag.Value, so it can be bound directly to a command-line flag.

Both SI (base 10: K, M, G, T, P, E) and IEC (base 2: Ki, Mi, Gi, Ti, Pi, Ei) suffixes are accepted on input. Output always uses the base 10 units.

The fmtFrac and fmtInt helpers used by Capacity.String are adapted from the standard library's time package, which uses the same technique to format Duration without allocating:

Source:  time/format.go (fmtFrac, fmtInt)
License: BSD 3-Clause (https://go.dev/LICENSE)

This package depends only on the standard library.

Index

• Constants
• Variables
• type Capacity
  • func ParseCapacity(s string) (Capacity, error)
  • func (c Capacity) Bytes() uint64
  • func (c Capacity) Exabytes() uint64
  • func (c Capacity) Exbibytes() uint64
  • func (c Capacity) Gibibytes() uint64
  • func (c Capacity) Gigabytes() uint64
  • func (c Capacity) Kibibytes() uint64
  • func (c Capacity) Kilobytes() uint64
  • func (c Capacity) Mebibytes() uint64
  • func (c Capacity) Megabytes() uint64
  • func (c Capacity) Pebibytes() uint64
  • func (c Capacity) Petabytes() uint64
  • func (c *Capacity) Set(s string) error
  • func (c Capacity) String() string
  • func (c Capacity) Tebibytes() uint64
  • func (c Capacity) Terabytes() uint64

Constants

const (
	Byte Capacity = 1

	Kilobyte = Byte * 1000
	Megabyte = Kilobyte * 1000
	Gigabyte = Megabyte * 1000
	Terabyte = Gigabyte * 1000
	Petabyte = Terabyte * 1000
	Exabyte  = Petabyte * 1000

	Kibibyte = Byte << 10
	Mebibyte = Kibibyte << 10
	Gibibyte = Mebibyte << 10
	Tebibyte = Gibibyte << 10
	Pebibyte = Tebibyte << 10
	Exbibyte = Pebibyte << 10
)

Variables

var ErrInvalidCapacity = errors.New("bytes: invalid capacity")

ErrInvalidCapacity is returned by ParseCapacity for any input it cannot parse. Errors returned by ParseCapacity wrap it, so callers can test with errors.Is.

Types

type Capacity

type Capacity uint64

A Capacity represents a size in bytes.

func ParseCapacity

func ParseCapacity(s string) (Capacity, error)

ParseCapacity parses a capacity string. A capacity string may only contain whole integers and one unit suffix, such as "10G" or "5T". Valid capacity units are:

"K", "M", "G", "T", "P", "E",
"Ki", "Mi", "Gi", "Ti", "Pi", "Ei"

A string with no suffix is taken as a plain bytes count. Every error returned wraps ErrInvalidCapacity.

func (Capacity) Bytes

func (c Capacity) Bytes() uint64

Bytes returns the capacity as an integer bytes count.

func (Capacity) Exabytes

func (c Capacity) Exabytes() uint64

Exabytes returns the capacity as an integer exabytes count.

func (Capacity) Exbibytes

func (c Capacity) Exbibytes() uint64

Exbibytes returns the capacity as an integer exbibytes count.

func (Capacity) Gibibytes

func (c Capacity) Gibibytes() uint64

Gibibytes returns the capacity as an integer gibibytes count.

func (Capacity) Gigabytes

func (c Capacity) Gigabytes() uint64

Gigabytes returns the capacity as an integer gigabytes count.

func (Capacity) Kibibytes

func (c Capacity) Kibibytes() uint64

Kibibytes returns the capacity as an integer kibibytes count.

func (Capacity) Kilobytes

func (c Capacity) Kilobytes() uint64

Kilobytes returns the capacity as an integer kilobytes count.

func (Capacity) Mebibytes

func (c Capacity) Mebibytes() uint64

Mebibytes returns the capacity as an integer mebibytes count.

func (Capacity) Megabytes

func (c Capacity) Megabytes() uint64

Megabytes returns the capacity as an integer megabytes count.

func (Capacity) Pebibytes

func (c Capacity) Pebibytes() uint64

Pebibytes returns the capacity as an integer pebibytes count.

func (Capacity) Petabytes

func (c Capacity) Petabytes() uint64

Petabytes returns the capacity as an integer petabytes count.

func (*Capacity) Set

func (c *Capacity) Set(s string) error

Set parses the given string and sets the receiver to the parsed value. It implements flag.Value alongside String.

func (Capacity) String

func (c Capacity) String() string

String returns a string representing the capacity in the form of "10.4G" representing their base 10 measurement, gigabytes in this example. Capacities are rounded to the nearest 1/10th within the largest unit of granularity. This format is similar to the "human" output from common Linux tools.

func (Capacity) Tebibytes

func (c Capacity) Tebibytes() uint64

Tebibytes returns the capacity as an integer tebibytes count.

func (Capacity) Terabytes

func (c Capacity) Terabytes() uint64

Terabytes returns the capacity as an integer terabytes count.