bytesize

README

📏 ByteSize Package

A Go package for handling byte sizes using IEC binary units (powers of 1024). It provides parsing, formatting, and arithmetic operations for byte sizes from Bytes up to Pebibytes.

🎯 Features

• 🔌 Interfacing:

  • JSON Marshaler/Unmarshaler for IEC string representation
  • Stringer for human-readable output

• 💾 Dual Representation:

  • Maintains both truncated integer (int64) and exact floating-point (float64) values
  • Provides canonical string representation (e.g., "42.5MiB")
  • Value accessors:
    • Bytes() returns truncated int64 (e.g., "42.42MiB" → 44480593)
    • Exact() returns float64 (e.g., "42.42MiB" → 44480593.92)
    • String() returns canonical string (e.g., "42.42MiB")

• 📊 Size Support:

  • Range from 0B to ~9 EiB (maximum int64 value)
  • Supports negative values and floating-point components
  • Truncates toward zero without rounding to prevent overflows
  • Integer overflow detection

• 🔤 String Operations:

  • Parse size strings in format "NUMBER[OPTIONNAL UNIT]" (e.g., "42", "42.5MiB", "1.2GiB")
  • Automatic unit selection for human-readable output
  • Converts short unit forms to IEC standard (e.g., "M" to "MiB")
  • Rounds to 2 decimal places (except for bytes)

• 🧮 Arithmetic Operations:

  • Add sizes together with overflow protection
  • Work with raw byte counts or formatted strings

📐 Understanding Units

This package uses IEC binary units (powers of 1024) rather than SI decimal units (powers of 1000):

🖥️ IEC Binary Units (This Package)

• Uses powers of 1024 (2¹⁰)
• Clear "binary" notation with "i" (KiB, MiB, GiB)
• Matches how computers actually store data (binary notation)

1 KiB = 1024 bytes
1 MiB = 1024 KiB = 1,048,576 bytes
1 GiB = 1024 MiB = 1,073,741,824 bytes

📊 SI Decimal Units

• Uses powers of 1000
• Traditional notation (KB, MB, GB)
• Common in marketing and data transmission

1 KB = 1000 bytes
1 MB = 1000 KB = 1,000,000 bytes
1 GB = 1000 MB = 1,000,000,000 bytes

💡 Example: A "500 GB" hard drive using SI units (500,000,000,000 bytes) shows as "465.7 GiB" in most operating systems, which use IEC binary units internally.

⚠️ Important Notes

• Partial bytes not supported (e.g., "1.5 Bytes") - would require arbitrary byte width
• Error handling covers:
  • Empty string input
  • No numeric value found
  • Invalid IEC unit symbol
  • Integer overflow from too large value
  • Invalid JSON input type

📜 License

This library is licensed under the GNU Lesser General Public License v3.0 or later (LGPL v3 or later).

Documentation

Overview

Package bytesize provides functionality for handling byte size values using IEC binary units (powers of 1024). It offers parsing, formatting, and arithmetic operations for byte sizes from Bytes up to Pebibytes.

The package focuses on IEC binary units (KiB, MiB, etc.) rather than SI decimal units (KB, MB, etc.) to avoid ambiguity in size representations. It supports:

• Parsing size strings with units (e.g., "42.5MiB", "1.2GiB")
• Converting between different units
• Basic arithmetic operations on sizes
• Handling negative and floating-point values
• Range limited to what int64 can represent (approximately 9 EiB)

Index

• Constants
• Variables
• func Parse(s string) (truncated int64, fractional float64, representation string, err error)
• func ToString(b float64) string
• type Size
  • func New(s string) (Size, error)
  • func NewInt(i int64) Size
  • func (s *Size) Add(value string) error
  • func (s *Size) AddInt(i int64) error
  • func (s Size) Bytes() int64
  • func (s Size) Exact() float64
  • func (b Size) MarshalJSON() ([]byte, error)
  • func (s Size) String() string
  • func (d *Size) UnmarshalJSON(b []byte) error

Constants

const (
	// Base IEC binary units in bytes, each a power of 1024
	Byte int64 = 1 << (10 * iota) // 1 byte
	Kibi
	Mebi
	Gibi
	Tebi
	Pebi

	// IEC binary unit symbols
	ByteSymbol = "B"   // Byte
	KibiSymbol = "KiB" // Kibibyte
	MebiSymbol = "MiB" // Mebibyte
	GibiSymbol = "GiB" // Gibibyte
	TebiSymbol = "TiB" // Tebibyte
	PebiSymbol = "PiB" // Pebibyte

	// Error messages
	ErrEmptyString     = "A Size string value cannot be empty"
	ErrNoValue         = "No numeric value found in the given string"
	ErrInvalidIEC      = "Invalid IEC unit symbol in Size string"
	ErrIntegerOverflow = "Size value is too large to be represented as an int64"
)

const (
	ErrJSONInvalidType = "invalid JSON byte Size type, it should be a string or a number"
)

Variables

var ByteSymbolIEC = [...]string{
	ByteSymbol,
	KibiSymbol,
	MebiSymbol,
	GibiSymbol,
	TebiSymbol,
	PebiSymbol,
}

ByteSymbolIEC contains the string symbols for each IEC binary unit in ascending order. The index of each symbol corresponds to the same index in ByteValueIEC.

var ByteValueIEC = [...]int64{
	Byte,
	Kibi,
	Mebi,
	Gibi,
	Tebi,
	Pebi,
}

ByteValueIEC contains the byte values for each IEC binary unit in ascending order. This slice is used internally for unit conversion and formatting.

Functions

func Parse

func Parse(s string) (
	truncated int64, fractional float64, representation string, err error,
)

Parse parses a string representation of a byte size with IEC binary units and returns its components.

It accepts strings in the format "NUMBER[UNIT]" where:

• number can be an integer, floating-point, or negative value
• unit is an optional IEC binary unit (B, KiB, MiB, GiB, TiB, PiB)

Truncated value are simple truncation toward zero with no rounding.

• We don't want to risk an overflow by rounding to the nearest value (-2.5 => -2, 2.5 => 3) or flooring to the nearest negative value (-2.5 => -3, 2.5 => 2).
• We "can't" use partial byte like "1.5 Bytes = 8 bits + 4 bits",

that require to set an arbitrary Byte width, which is most likely not what you want.

The function returns:

• truncated: the size in bytes as an int64, truncated toward zero
• fractional: the exact size in bytes as a float64
• representation: the canonical IEC string representation
• error: if the input is invalid or the value is too large

Examples:

Parse("42.42M") returns (44480593, 44480593.92, "42.42MiB", nil)
Parse("1024") returns (1024, 1024.0, "1KiB", nil)
Parse("-2.5KiB") returns (-2560, -2560.0, "-2.5KiB", nil)

If a short unit symbol is used (e.g., "M" instead of "MiB"), it is automatically converted to the canonical IEC to avoid ambiguity with SI decimal units.

func ToString

func ToString(b float64) string

ToString returns a string representing the Size value in IEC format. It uses the most appropriate unit to keep the number human-readable.

Types

type Size

type Size struct {
	// contains filtered or unexported fields
}

Size represents a byte size value with both truncated integer and exact floating-point representations and stores the IEC string representation of the size.

func New

func New(s string) (Size, error)

New creates a new Size from a string representation. It uses Parse and returns a Size struct or an error if the input is invalid.

func NewInt

func NewInt(i int64) Size

NewInt creates a new Size from an int64 value representing bytes. This is useful when you have a byte count and want to convert it to a human-readable format with appropriate IEC binary units.

func (*Size) Add

func (s *Size) Add(value string) error

Add adds the given size string to the current Size. The size string must be in a valid format as accepted by Parse. Returns an error if the input string is invalid or if the result would overflow.

func (*Size) AddInt

func (s *Size) AddInt(i int64) error

AddInt adds the given number of bytes to the current Size. This is a more efficient alternative to Add when working with raw byte counts.

func (Size) Bytes

func (s Size) Bytes() int64

Bytes returns the Byte count of the Size as an int64. It is truncated toward zero across positive and negative values (e.g., "42.42MiB" => 44480593)

func (Size) Exact

func (s Size) Exact() float64

Exact returns the floating-point value of the byte size as a float64. (e.g., "42.42MiB" => 44480593.92)

func (Size) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface.

func (Size) String

func (s Size) String() string

String is the stringer method for the Size struct. It returns the canonical IEC string representation of the Size.

func (*Size) UnmarshalJSON

func (d *Size) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.