bytefmt

README

bytefmt

Package bytefmt is a utility to parse, format, and manipulate byte quantities. This package emphasizes accuracy and adherence to standards over performance and implements both binary and decimal International System of Units (SI) conventions.

This package is inspired by Kubernetes' resource.Quantity. It carries no dependencies and a simplified interface focused strictly on byte quantities.

Alternatives

• code.cloudfoundry.org/bytefmt: Simple, fast, and popular. This package assumes Binary SI convention and is limited to float64 precision.

• k8s.io/apimachinery/pkg/api/resource: resource.Quantity provides exact precision, multiple standards, and arbitrarily large values. Being part of the larger Kubernetes API, it pulls in a long list of dependencies

• github.com/inhies/go-bytesize: bytesize.ByteSize Supports parsing and formatting full-word units such as "gigabyte". This package assumes Binary SI convention, but does not support SI prefixes: Ki, Mi, Gi, .... It is limited to int64 values.

Documentation

Overview

Package bytefmt is a utility to parse, format, and manipulate byte quantities. This package emphasizes accuracy and adherence to standards over performance and implements both binary and decimal International System of Units (SI) conventions.

Index

• Constants
• type Base
• type NullSize
  • func (s NullSize) MarshalJSON() ([]byte, error)
  • func (s *NullSize) Scan(value interface{}) error
  • func (s *NullSize) UnmarshalJSON(value []byte) error
  • func (s NullSize) Value() (driver.Value, error)
• type Size
  • func New(bytes int64, base Base) *Size
  • func Parse(s string) (*Size, error)
  • func (s *Size) Add(y Size)
  • func (s *Size) Cmp(y Size) int
  • func (s Size) Equal(y Size) bool
  • func (s Size) Format(f fmt.State, verb rune)
  • func (s Size) Int64() int64
  • func (s Size) IsZero() bool
  • func (s Size) MarshalJSON() ([]byte, error)
  • func (s Size) MarshalText() ([]byte, error)
  • func (s *Size) Neg()
  • func (s *Size) Scan(value interface{}) error
  • func (s *Size) SetInt64(bytes int64)
  • func (s Size) Sign() int
  • func (s Size) String() string
  • func (s *Size) Sub(y Size)
  • func (s *Size) UnmarshalJSON(value []byte) error
  • func (s *Size) UnmarshalText(value []byte) error
  • func (s Size) Value() (driver.Value, error)

Constants

const (
	KB = 1000 * Byte
	MB = 1000 * KB
	GB = 1000 * MB
	TB = 1000 * GB
	PB = 1000 * TB
)

Metric suffixes scale quantities by powers of 1000.

const (
	KiB = 1024 * Byte
	MiB = 1024 * KiB
	GiB = 1024 * MiB
	TiB = 1024 * GiB
	PiB = 1024 * TiB
)

Binary suffixes scale quantities by powers of 1024.

const Byte int64 = 1

Byte is the unscaled unit for bytes.

Types

type Base

type Base int

Base is a radix by which byte quantities can be scaled.

const (
	// Metric units define powers of 1000 using SI decimal prefixes per NIST.
	// https://physics.nist.gov/cuu/Units/prefixes.html
	Metric Base = 1000

	// Binary units define powers of 2^10 using SI binary prefixes per the IEC.
	// https://physics.nist.gov/cuu/Units/binary.html
	Binary Base = 1024
)

type NullSize

type NullSize struct {
	Size  Size
	Valid bool
}

NullSize is a nullable representation of Size.

func (NullSize) MarshalJSON

func (s NullSize) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*NullSize) Scan

func (s *NullSize) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

func (*NullSize) UnmarshalJSON

func (s *NullSize) UnmarshalJSON(value []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

func (NullSize) Value

func (s NullSize) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type Size

type Size struct {

	// Base determines how a byte quantity is formatted. If unset it defaults to
	// Metric, or Decimal SI prefixes.
	Base Base
	// contains filtered or unexported fields
}

Size is a count of bytes with human-friendly unit scaling.

func New

func New(bytes int64, base Base) *Size

New returns a new size from a count of bytes.

func Parse

func Parse(s string) (*Size, error)

Parse converts a string representation of a byte quantity to a Size. Fractional values are truncated to the nearest byte, rounding toward zero.

Parsed values retain their base format, defaulting to Metric if the suffix is missing. Unit prefixes are permissive for Metric scales ("K" = "kB"), but strict for Binary scales ("KiB").

Parse("1024")     = 1,024 B  = 1,024 bytes
Parse("1024k")    = 1,024 kB = 1,024,000 bytes
Parse("1.1gb")    = 1100 MB  = 1,100,000,000 bytes
Parse("1.25 GiB") = 1.25 GiB = 1,342,177,280 bytes

func (*Size) Add

func (s *Size) Add(y Size)

Add adds size y to the current value.

func (*Size) Cmp

func (s *Size) Cmp(y Size) int

Cmp compares s and t and returns:

-1 if s <  y
 0 if s == y
+1 if s >  y

func (Size) Equal

func (s Size) Equal(y Size) bool

Equal returns whether two sizes represent the same number of bytes.

func (Size) Format

func (s Size) Format(f fmt.State, verb rune)

Format implements the fmt.Formatter interface.

The following verbs are supported:

• 'f': Precision is expressed in decimal places; trailing zeros are preserved.
• 'g': Precision is expressed in significant figures; trailing zeros are removed.
• 'v': Equivalent to '%.4g'.

Setting width is not supported. Flags are also not supported.

The largest base unit smaller than the quantity is used. For example, 999 bytes is formatted as "999 B" and 1000 bytes is formatted as "1 kB".

func (Size) Int64

func (s Size) Int64() int64

Int64 returns a size's representation as an absolute number of bytes.

func (Size) IsZero

func (s Size) IsZero() bool

IsZero returns whether a size is exactly zero bytes.

func (Size) MarshalJSON

func (s Size) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (Size) MarshalText

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

MarshalText implements the encoding.TextMarshaler interface.

func (*Size) Neg

func (s *Size) Neg()

Neg sets the current value to -s.

func (*Size) Scan

func (s *Size) Scan(value interface{}) error

Scan implements the sql.Scanner interface. It accepts numeric and string values.

func (*Size) SetInt64

func (s *Size) SetInt64(bytes int64)

SetInt64 overrides a size's byte count while leaving its unit scale unchanged.

func (Size) Sign

func (s Size) Sign() int

Sign compares s against 0 and returns:

-1 if s <  0
 0 if s == 0
+1 if s >  0

func (Size) String

func (s Size) String() string

String returns the formatted quantity scaled to the largest exact base unit.

func (*Size) Sub

func (s *Size) Sub(y Size)

Sub subtracts size y from the current value.

func (*Size) UnmarshalJSON

func (s *Size) UnmarshalJSON(value []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

func (*Size) UnmarshalText

func (s *Size) UnmarshalText(value []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

func (Size) Value

func (s Size) Value() (driver.Value, error)

Value implements the sql.Valuer interface. It always produces a string.