bytesize

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 27, 2026 License: MIT Imports: 9 Imported by: 0

README

ByteSize

Go Reference Go Coverage Status Go Report Card

This package is based off two others; so the credit and inspiration goes to:

I took from these packages and made into something I personally wanted and or needed at the time.

Documentation

Overview

Package bytesize provides a type for representing byte sizes with support for both decimal (SI) and binary (IEC) units, as well as parsing from strings and formatting to human-readable strings.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	None = Bytes{0, 0}
	One  = Bytes{1, 0}

	B  = One
	KB = Bytes(Uint128(B).Mul64(1e3))  // 1e3
	MB = Bytes(Uint128(KB).Mul64(1e3)) // 1e6
	GB = Bytes(Uint128(MB).Mul64(1e3)) // 1e9
	TB = Bytes(Uint128(GB).Mul64(1e3)) // 1e12
	PB = Bytes(Uint128(TB).Mul64(1e3)) // 1e15
	EB = Bytes(Uint128(PB).Mul64(1e3)) // 1e18
	ZB = Bytes(Uint128(EB).Mul64(1e3)) // 1e21
	YB = Bytes(Uint128(ZB).Mul64(1e3)) // 1e24
	RB = Bytes(Uint128(YB).Mul64(1e3)) // 1e27
	QB = Bytes(Uint128(RB).Mul64(1e3)) // 1e30
)

Decimal byte size units (powers of 10).

View Source 
var (
	KiB = Bytes{1024, 0}
	MiB = Bytes{uint64(math.Pow(1024, 2)), 0}
	GiB = Bytes{uint64(math.Pow(1024, 3)), 0}
	TiB = Bytes{uint64(math.Pow(1024, 4)), 0}
	PiB = Bytes{uint64(math.Pow(1024, 5)), 0}
	EiB = Bytes{uint64(math.Pow(1024, 6)), 0}
	// ZB (2^70) and YB (2^80) cannot be represented as a single
	// uint64, so we use the high bits.
	// 2^70 = 2^(64+6) = 2^64 * 2^6 = (1 << 6) in the high bits.
	ZiB = Bytes{0, 1 << 6}
	// 2^80 = 2^(64+16) = 2^64 * 2^16 = (1 << 16) in the high bits.
	YiB = Bytes{0, 1 << 16}
	// 2^90 = 2^(64+26) = 2^64 * 2^26 = (1 << 26) in the high bits.
	RiB = Bytes{0, 1 << 26}
	// 2^100 = 2^(64+36) = 2^64 * 2^36 = (1 << 36) in the high bits.
	QiB = Bytes{0, 1 << 36}
)

Binary byte size units (powers of 2).

View Source 
var (
	// DefaultFormatStr is the default format string for formatting byte
	// sizes, which includes two decimal places and the unit.
	DefaultFormatStr = "%.2f %s"
	// DefaultForcedUnitType is the default forced unit for formatting byte
	// sizes, which is nil to indicate automatic unit selection based on the
	// value.
	DefaultForcedUnitType *Bytes
	// DefaultLongUnits indicates whether to use long unit names, such
	// as "Megabyte" instead of "MB", though the default is to use short unit
	// names.
	DefaultLongUnits = false
	// DefaultDecimalUnits indicates whether to use decimal (SI) units by default
	DefaultDecimalUnits = true
)

These default options can be overridden by users of this package

View Source 
var LongBinary = map[Bytes]string{
	KiB: "Kibibyte",
	MiB: "Mebibyte",
	GiB: "Gibibyte",
	TiB: "Tebibyte",
	PiB: "Pebibyte",
	EiB: "Exbibyte",
	ZiB: "Zebibyte",
	YiB: "Yobibyte",
	RiB: "Ronnibyte",
	QiB: "Quettibyte",
}

LongBinary maps binary byte size units to their long names.

View Source 
var LongDecimal = map[Bytes]string{
	KB: "Kilobyte",
	MB: "Megabyte",
	GB: "Gigabyte",
	TB: "Terabyte",
	PB: "Petabyte",
	EB: "Exabyte",
	ZB: "Zettabyte",
	YB: "Yottabyte",
	RB: "Ronnabyte",
	QB: "Quettabyte",
}

LongDecimal maps decimal byte size units to their long names.

View Source 
var Max = NewUint128(math.MaxUint64, math.MaxUint64)

Max is the largest possible uint128 value.

View Source 
var ShortBinary = map[Bytes]string{
	KiB: "KiB",
	MiB: "MiB",
	GiB: "GiB",
	TiB: "TiB",
	PiB: "PiB",
	EiB: "EiB",
	ZiB: "ZiB",
	YiB: "YiB",
	RiB: "RiB",
	QiB: "QiB",
}

ShortBinary maps binary byte size units to their short names.

View Source 
var ShortDecimal = map[Bytes]string{
	KB: "KB",
	MB: "MB",
	GB: "GB",
	TB: "TB",
	PB: "PB",
	EB: "EB",
	ZB: "ZB",
	YB: "YB",
	RB: "RB",
	QB: "QB",
}

ShortDecimal maps decimal byte size units to their short names.

View Source 
var UnitStringToBytes = map[string]Bytes{
	"b":  B,
	"kb": KB, "mb": MB, "gb": GB, "tb": TB, "pb": PB, "eb": EB, "zb": ZB, "yb": YB, "rb": RB, "qb": QB,
	"kib": KiB, "mib": MiB, "gib": GiB, "tib": TiB, "pib": PiB, "eib": EiB, "zib": ZiB, "yib": YiB, "rib": RiB, "qib": QiB,
	"byte": B, "bytes": B,
	"kilobyte": KB, "kilobytes": KB, "megabyte": MB, "megabytes": MB, "gigabyte": GB, "gigabytes": GB,
	"terabyte": TB, "terabytes": TB, "petabyte": PB, "petabytes": PB, "exabyte": EB, "exabytes": EB, "zettabyte": ZB, "zettabytes": ZB, "yottabyte": YB, "yottabytes": YB,
	"ronnabyte": RB, "ronnabytes": RB, "quettabyte": QB, "quettabytes": QB,
	"kibibyte": KiB, "kibibytes": KiB, "mebibyte": MiB, "mebibytes": MiB, "gibibyte": GiB, "gibibytes": GiB,
	"tebibyte": TiB, "tebibytes": TiB, "pebibyte": PiB, "pebibytes": PiB, "exbibyte": EiB, "exbibytes": EiB,
	"zebibyte": ZiB, "zebibytes": ZiB, "yobibyte": YiB, "yobibytes": YiB, "ronnibyte": RiB, "ronnibytes": RiB, "quettibyte": QiB, "quettibytes": QiB,
}

UnitStringToBytes maps valid unit strings to their corresponding Bytes multiplier values for parsing.

View Source 
var ValidUnits = []string{
	"b",
	"kb", "mb", "gb", "tb", "pb", "eb", "zb", "yb", "rb", "qb",
	"kib", "mib", "gib", "tib", "pib", "eib", "zib", "yib", "rib", "qib",
	"byte", "bytes",
	"kilobyte", "kilobytes", "megabyte", "megabytes", "gigabyte", "gigabytes", "terabyte", "terabytes", "petabyte", "petabytes",
	"exabyte", "exabytes", "zettabyte", "zettabytes", "yottabyte", "yottabytes", "ronnabyte", "ronnabytes", "quettabyte", "quettabytes",
	"kibibyte", "kibibytes", "mebibyte", "mebibytes", "gibibyte", "gibibytes", "tebibyte", "tebibytes", "pebibyte", "pebibytes",
	"exbibyte", "exbibytes", "zebibyte", "zebibytes", "yobibyte", "yobibytes", "ronnibyte", "ronnibytes", "quettibyte", "quettibytes",
}

ValidUnits lists all supported unit strings for parsing.

Functions

func IsValidUnit 

func IsValidUnit(unit string) bool

IsValidUnit checks if the provided unit string is a valid unit for parsing byte sizes.

Example 
package main

import (
	"fmt"

	"github.com/beauhoyt/bytesize"
)

func main() {
	fmt.Printf("Is 'MB' a valid unit? %v\n", bytesize.IsValidUnit("MB"))
	fmt.Printf("Is 'invalid' a valid unit? %v\n", bytesize.IsValidUnit("invalid"))
}

Output:

Is 'MB' a valid unit? true
Is 'invalid' a valid unit? false

Types

type Bytes 

type Bytes Uint128

Bytes represents a byte size as a 128-bit unsigned integer, allowing for very large sizes up to 2^128 - 1 bytes.

Example 
package main

import (
	"fmt"

	"github.com/beauhoyt/bytesize"
)

func main() {
	bs := bytesize.Bytes{123456789, 0}
	fmt.Printf("%s\n", bs)
}

Output:

123.46 MB

func Parse 

func Parse(s string) (Bytes, error)

Parse parses a string representation of a byte size (e.g., "10 MB", "5.5 GiB", "100 kilobytes", "2.34 Tebibytes") returns the corresponding Bytes value.

Example 
package main

import (
	"fmt"

	"github.com/beauhoyt/bytesize"
)

func main() {
	bs, err := bytesize.Parse("123.45 MB")
	if err != nil {
		fmt.Printf("Error parsing byte size: %v", err)
		return
	}
	fmt.Printf("%s\n", bs)
}

Output:

123.45 MB

func (Bytes) Format 

func (b Bytes) Format(opts ...FormatOption) (string, error)

Format formats the Bytes value as a human-readable string using the specified options. It returns the formatted string or an error if any of the options are invalid.

Example 
package main

import (
	"fmt"

	"github.com/beauhoyt/bytesize"
)

func main() {
	bs := bytesize.Bytes{1234567890, 0}
	formatStr, err := bs.Format(bytesize.WithForcedUnit(bytesize.MiB))
	if err != nil {
		fmt.Printf("Error formatting byte size: %v\n", err)
		return
	}
	fmt.Printf("%s\n", formatStr)
}

Output:

1177.38 MiB

func (*Bytes) Get 

func (b *Bytes) Get() any

Get implements the flag.Getter interface for Bytes.

func (*Bytes) Set 

func (b *Bytes) Set(s string) error

Set implements the flag.Value interface for Bytes.

func (Bytes) String 

func (b Bytes) String() string

func (*Bytes) Type 

func (b *Bytes) Type() string

Type implements the flag.Value interface for Bytes.

func (*Bytes) UnmarshalText 

func (b *Bytes) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface for Bytes.

type FormatOption 

type FormatOption func(*formatOptions) error

FormatOption defines a functional option for configuring the formatting of byte sizes.

func WithDecimalUnits 

func WithDecimalUnits(decimalUnits bool) FormatOption

WithDecimalUnits allows you to specify whether to use decimal (SI) units or binary (IEC) units when formatting byte sizes. If true, it will use decimal units (KB, MB, etc.); if false, it will use binary units (KiB, MiB, etc.).

func WithForcedUnit 

func WithForcedUnit(unit Bytes) FormatOption

WithForcedUnit allows you to specify a specific unit to use when formatting byte sizes. If not set, the formatting will automatically choose the most appropriate unit based on the value.

func WithFormatString 

func WithFormatString(formatStr string) FormatOption

WithFormatString allows you to specify a custom format string for formatting byte sizes. The format string should include two verbs: one for the value (e.g., %.2f) and one for the unit (e.g., %s).

func WithLongUnits 

func WithLongUnits(longUnits bool) FormatOption

WithLongUnits allows you to specify whether to use long unit names (e.g., "Megabyte") or short unit names (e.g., "MB") when formatting byte sizes.

type Uint128 

type Uint128 struct {
	Lo, Hi uint64
}

A Uint128 is an unsigned 128-bit number. 

var Zero Uint128

Zero is a zero-valued uint128.

func From64 

func From64(v uint64) Uint128

From64 converts v to a Uint128 value.

func FromBig 

func FromBig(i *big.Int) (u Uint128)

FromBig converts i to a Uint128 value. It panics if i is negative or overflows 128 bits.

func FromBigErr added in v0.1.0 

func FromBigErr(i *big.Int) (u Uint128, err error)

FromBigErr converts i to a Uint128 value, returning an error if i is negative or overflows 128 bits.

func FromBytes 

func FromBytes(b []byte) Uint128

FromBytes converts b to a Uint128 value.

func FromBytesBE 

func FromBytesBE(b []byte) Uint128

FromBytesBE converts big-endian b to a Uint128 value.

func FromString 

func FromString(s string) (u Uint128, err error)

FromString parses s as a Uint128 value.

func NewUint128 

func NewUint128(lo, hi uint64) Uint128

NewUint128 returns the Uint128 value (lo,hi).

func (Uint128) Add 

func (u Uint128) Add(v Uint128) Uint128

Add returns u+v.

func (Uint128) Add64 

func (u Uint128) Add64(v uint64) Uint128

Add64 returns u+v.

func (Uint128) Add64Err added in v0.1.0 

func (u Uint128) Add64Err(v uint64) (Uint128, error)

Add64Err returns u+v, returning an error on overflow.

func (Uint128) AddBytes added in v0.3.0 

func (u Uint128) AddBytes(v Bytes) Uint128

AddBytes returns u+v. It panics on overflow.

func (Uint128) AddBytesErr added in v0.3.0 

func (u Uint128) AddBytesErr(v Bytes) (Uint128, error)

AddBytesErr returns u+v, returning an error on overflow.

func (Uint128) AddErr added in v0.1.0 

func (u Uint128) AddErr(v Uint128) (Uint128, error)

AddErr returns u+v, returning an error on overflow.

func (Uint128) AddWrap 

func (u Uint128) AddWrap(v Uint128) Uint128

AddWrap returns u+v with wraparound semantics; for example, Max.AddWrap(From64(1)) == Zero.

func (Uint128) AddWrap64 

func (u Uint128) AddWrap64(v uint64) Uint128

AddWrap64 returns u+v with wraparound semantics; for example, Max.AddWrap64(1) == Zero.

func (Uint128) AddWrapBytes added in v0.3.0 

func (u Uint128) AddWrapBytes(v Bytes) Uint128

AddWrapBytes returns u+v with wraparound semantics; for example, Max.AddWrapBytes(Bytes{1,0})) == Zero.

func (Uint128) And 

func (u Uint128) And(v Uint128) Uint128

And returns u&v.

func (Uint128) And64 

func (u Uint128) And64(v uint64) Uint128

And64 returns u&v.

func (Uint128) AndBytes added in v0.3.0 

func (u Uint128) AndBytes(v Bytes) Uint128

AndBytes returns u&v.

func (Uint128) AppendBytes 

func (u Uint128) AppendBytes(b []byte) []byte

AppendBytes appends u to b in little-endian order and returns the extended buffer.

func (Uint128) AppendBytesBE 

func (u Uint128) AppendBytesBE(b []byte) []byte

AppendBytesBE appends u to b in big-endian order and returns the extended buffer.

func (Uint128) Big 

func (u Uint128) Big() *big.Int

Big returns u as a *big.Int.

func (Uint128) Cmp 

func (u Uint128) Cmp(v Uint128) int

Cmp compares u and v and returns: 

-1 if u <  v
 0 if u == v
+1 if u >  v

func (Uint128) Cmp64 

func (u Uint128) Cmp64(v uint64) int

Cmp64 compares u and v and returns: 

-1 if u <  v
 0 if u == v
+1 if u >  v

func (Uint128) CmpBytes added in v0.3.0 

func (u Uint128) CmpBytes(v Bytes) int

CmpBytes compares u and v and returns: 

-1 if u <  v
 0 if u == v
+1 if u >  v

func (Uint128) Div 

func (u Uint128) Div(v Uint128) Uint128

Div returns u/v.

func (Uint128) Div64 

func (u Uint128) Div64(v uint64) Uint128

Div64 returns u/v.

func (Uint128) DivBytes added in v0.3.0 

func (u Uint128) DivBytes(v Bytes) Uint128

DivBytes returns u/v.

func (Uint128) Equals 

func (u Uint128) Equals(v Uint128) bool

Equals returns true if u == v.

Uint128 values can be compared directly with ==, but use of the Equals method is preferred for consistency.

func (Uint128) Equals64 

func (u Uint128) Equals64(v uint64) bool

Equals64 returns true if u == v.

func (Uint128) EqualsBytes added in v0.3.0 

func (u Uint128) EqualsBytes(v Bytes) bool

EqualsBytes returns true if u == v.

func (Uint128) IsZero 

func (u Uint128) IsZero() bool

IsZero returns true if u == 0.

func (Uint128) LeadingZeros 

func (u Uint128) LeadingZeros() int

LeadingZeros returns the number of leading zero bits in u; the result is 128 for u == 0.

func (Uint128) Len 

func (u Uint128) Len() int

Len returns the minimum number of bits required to represent u; the result is 0 for u == 0.

func (Uint128) Lsh 

func (u Uint128) Lsh(n uint) (s Uint128)

Lsh returns u<<n.

func (Uint128) MarshalText 

func (u Uint128) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Uint128) Mod 

func (u Uint128) Mod(v Uint128) (r Uint128)

Mod returns r = u%v.

func (Uint128) Mod64 

func (u Uint128) Mod64(v uint64) (r uint64)

Mod64 returns r = u%v.

func (Uint128) ModBytes added in v0.3.0 

func (u Uint128) ModBytes(v Bytes) (r Uint128)

ModBytes returns r = u%v.

func (Uint128) Mul 

func (u Uint128) Mul(v Uint128) Uint128

Mul returns u*v, panicking on overflow.

func (Uint128) Mul64 

func (u Uint128) Mul64(v uint64) Uint128

Mul64 returns u*v, panicking on overflow.

func (Uint128) Mul64Err added in v0.1.0 

func (u Uint128) Mul64Err(v uint64) (Uint128, error)

Mul64Err returns u*v, returning an error on overflow.

func (Uint128) MulBytes added in v0.3.0 

func (u Uint128) MulBytes(v Bytes) Uint128

MulBytes returns u*v, panicking on overflow.

func (Uint128) MulBytesErr added in v0.3.0 

func (u Uint128) MulBytesErr(v Bytes) (Uint128, error)

MulBytesErr returns u*v, returning an error on overflow.

func (Uint128) MulErr added in v0.1.0 

func (u Uint128) MulErr(v Uint128) (Uint128, error)

MulErr returns u*v, returning an error on overflow.

func (Uint128) MulWrap 

func (u Uint128) MulWrap(v Uint128) Uint128

MulWrap returns u*v with wraparound semantics; for example, Max.MulWrap(Max) == 1.

func (Uint128) MulWrap64 

func (u Uint128) MulWrap64(v uint64) Uint128

MulWrap64 returns u*v with wraparound semantics; for example, Max.MulWrap64(2) == Max.Sub64(1).

func (Uint128) MulWrapBytes added in v0.3.0 

func (u Uint128) MulWrapBytes(v Bytes) Uint128

MulWrapBytes returns u*v with wraparound semantics; for example, Max.MulWrapBytes(Bytes{1,0}) == Max.

func (Uint128) OnesCount 

func (u Uint128) OnesCount() int

OnesCount returns the number of one bits ("population count") in u.

func (Uint128) Or 

func (u Uint128) Or(v Uint128) Uint128

Or returns u|v.

func (Uint128) Or64 

func (u Uint128) Or64(v uint64) Uint128

Or64 returns u|v.

func (Uint128) OrBytes added in v0.3.0 

func (u Uint128) OrBytes(v Bytes) Uint128

OrBytes returns u|v.

func (Uint128) PutBytes 

func (u Uint128) PutBytes(b []byte)

PutBytes stores u in b in little-endian order. It panics if len(b) < 16.

func (Uint128) PutBytesBE 

func (u Uint128) PutBytesBE(b []byte)

PutBytesBE stores u in b in big-endian order. It panics if len(ip) < 16.

func (Uint128) QuoRem 

func (u Uint128) QuoRem(v Uint128) (q, r Uint128)

QuoRem returns q = u/v and r = u%v.

func (Uint128) QuoRem64 

func (u Uint128) QuoRem64(v uint64) (q Uint128, r uint64)

QuoRem64 returns q = u/v and r = u%v.

func (Uint128) QuoRemBytes added in v0.3.0 

func (u Uint128) QuoRemBytes(v Bytes) (q, r Uint128)

QuoRemBytes returns q = u/v and r = u%v.

func (Uint128) Reverse 

func (u Uint128) Reverse() Uint128

Reverse returns the value of u with its bits in reversed order.

func (Uint128) ReverseBytes 

func (u Uint128) ReverseBytes() Uint128

ReverseBytes returns the value of u with its bytes in reversed order.

func (Uint128) RotateLeft 

func (u Uint128) RotateLeft(k int) Uint128

RotateLeft returns the value of u rotated left by (k mod 128) bits.

func (Uint128) RotateRight 

func (u Uint128) RotateRight(k int) Uint128

RotateRight returns the value of u rotated left by (k mod 128) bits.

func (Uint128) Rsh 

func (u Uint128) Rsh(n uint) (s Uint128)

Rsh returns u>>n.

func (*Uint128) Scan 

func (u *Uint128) Scan(s fmt.ScanState, ch rune) error

Scan implements fmt.Scanner.

func (Uint128) String 

func (u Uint128) String() string

String returns the base-10 representation of u as a string.

func (Uint128) Sub 

func (u Uint128) Sub(v Uint128) Uint128

Sub returns u-v. It panics on underflow.

func (Uint128) Sub64 

func (u Uint128) Sub64(v uint64) Uint128

Sub64 returns u-v. It panics on underflow.

func (Uint128) Sub64Err added in v0.1.0 

func (u Uint128) Sub64Err(v uint64) (Uint128, error)

Sub64Err returns u-v, returning an error on underflow.

func (Uint128) SubBytes added in v0.3.0 

func (u Uint128) SubBytes(v Bytes) Uint128

SubBytes returns u-v. It panics on underflow.

func (Uint128) SubBytesErr added in v0.3.0 

func (u Uint128) SubBytesErr(v Bytes) (Uint128, error)

SubBytesErr returns u-v, returning an error on underflow.

func (Uint128) SubErr added in v0.1.0 

func (u Uint128) SubErr(v Uint128) (Uint128, error)

SubErr returns u-v, returning an error on underflow.

func (Uint128) SubWrap 

func (u Uint128) SubWrap(v Uint128) Uint128

SubWrap returns u-v with wraparound semantics; for example, Zero.SubWrap(From64(1)) == Max.

func (Uint128) SubWrap64 

func (u Uint128) SubWrap64(v uint64) Uint128

SubWrap64 returns u-v with wraparound semantics; for example, Zero.SubWrap64(1) == Max.

func (Uint128) SubWrapBytes added in v0.3.0 

func (u Uint128) SubWrapBytes(v Bytes) Uint128

SubWrapBytes returns u-v with wraparound semantics; for example, Zero.SubWrapBytes(Bytes{1,0}) == Max.

func (Uint128) TrailingZeros 

func (u Uint128) TrailingZeros() int

TrailingZeros returns the number of trailing zero bits in u; the result is 128 for u == 0.

func (*Uint128) UnmarshalText 

func (u *Uint128) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (Uint128) Xor 

func (u Uint128) Xor(v Uint128) Uint128

Xor returns u^v.

func (Uint128) Xor64 

func (u Uint128) Xor64(v uint64) Uint128

Xor64 returns u^v.

func (Uint128) XorBytes added in v0.3.0 

func (u Uint128) XorBytes(v Bytes) Uint128

XorBytes returns u^v.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.