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.Quantityprovides 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.ByteSizeSupports 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
- type Size
- 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 ¶
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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
NullSize is a nullable representation of Size.
func (NullSize) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
func (*NullSize) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler 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 Parse ¶
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) Format ¶ added in v0.1.2
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) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
func (Size) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface.
func (*Size) Scan ¶
Scan implements the sql.Scanner interface. It accepts numeric and string values.
func (*Size) SetInt64 ¶
SetInt64 overrides a size's byte count while leaving its unit scale unchanged.
func (*Size) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface.
func (*Size) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface.
Source Files