Documentation
¶
Overview ¶
Package humanize provides utilities for formatting numbers into human-readable forms.
This package offers two main formatting capabilities:
Byte size formatting (IBytes): Converts byte counts to human-readable strings with binary prefixes (KiB, MiB, GiB, etc.).
Number formatting (Comma): Adds comma separators to numeric values for improved readability.
Both formatters support a fluent API with method chaining for setting precision.
Byte Formatting ¶
Use IBytes to format byte counts with binary (IEC) prefixes:
IBytes(1024).String() // "1 KiB" IBytes(1536000).String() // "1 MiB" IBytes(1536000).WithPrecision(2).String() // "1.46 MiB"
Supported units range from bytes (B) to exbibytes (EiB):
- B (bytes)
- KiB (kibibytes, 1024 bytes)
- MiB (mebibytes, 1024 KiB)
- GiB (gibibytes, 1024 MiB)
- TiB (tebibytes, 1024 GiB)
- PiB (pebibytes, 1024 TiB)
- EiB (exbibytes, 1024 PiB)
Number Formatting ¶
Use Comma to format numbers with comma separators:
Comma(int64(1234567)).String() // "1,234,567" Comma(1234567.89).String() // "1,234,567.89" Comma(1234567.89).WithPrecision(1).String() // "1,234,567.9"
The Comma function is generic and accepts any integer or floating-point type:
- Signed integers: int, int8, int16, int32, int64
- Unsigned integers: uint, uint8, uint16, uint32, uint64, uintptr
- Floating-point: float32, float64
Precision Control ¶
Both formatters support the WithPrecision method to control decimal places:
// IBytes: default rounds to nearest integer IBytes(1536).String() // "2 KiB" IBytes(1536).WithPrecision(1).String() // "1.5 KiB" IBytes(1536).WithPrecision(2).String() // "1.50 KiB" // Comma: integers default to no decimal, floats to natural precision Comma(1234).String() // "1,234" Comma(1234).WithPrecision(2).String() // "1,234.00" Comma(1234.567).WithPrecision(2).String() // "1,234.57"
Negative Values ¶
Both formatters correctly handle negative values:
IBytes(-1024).String() // "-1 KiB" Comma(-1234567).String() // "-1,234,567"
Edge Cases ¶
Special values are handled gracefully:
- Zero values: IBytes(0) returns "0 B"
- math.MinInt64: Handled without overflow
- Very large values (uint64 max): Correctly formatted
fmt.Formatter Interface ¶
Both formatters implement fmt.Formatter for use with printf-style functions:
fmt.Printf("Size: %v\n", IBytes(1024)) // "Size: 1 KiB"
fmt.Printf("Count: %v\n", Comma(1234567)) // "Count: 1,234,567"
This package is inspired by github.com/dustin/go-humanize but provides a simpler API optimized for internal use with full control over formatting behavior.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ByteFormatter ¶
type ByteFormatter struct {
// contains filtered or unexported fields
}
ByteFormatter formats byte sizes into human-readable strings with binary prefixes. Use IBytes to create a ByteFormatter, then optionally call WithPrecision before calling String to get the formatted result.
func IBytes ¶
func IBytes(b int64) *ByteFormatter
IBytes creates a new ByteFormatter for the given byte count. By default, values are rounded to the nearest integer unit. Call WithPrecision to specify decimal places.
Example:
IBytes(1536000).String() // "1 MiB" IBytes(1536000).WithPrecision(2).String() // "1.46 MiB"
func (*ByteFormatter) Format ¶
func (f *ByteFormatter) Format(st fmt.State, verb rune)
Format implements the fmt.Formatter interface for use with printf-style functions. The 'v' and 's' verbs are supported.
Example:
fmt.Printf("%v", IBytes(1536000)) // "1 MiB"
func (*ByteFormatter) String ¶
func (f *ByteFormatter) String() string
String formats the byte count as a human-readable string. Uses binary prefixes (KiB, MiB, GiB, etc.) and rounds to the precision set by WithPrecision (default 0).
Special cases:
- Zero returns "0 B"
- Negative values include a minus sign
- math.MinInt64 is handled gracefully
func (*ByteFormatter) WithPrecision ¶
func (f *ByteFormatter) WithPrecision(p int) *ByteFormatter
WithPrecision sets the number of decimal places to display. Returns the ByteFormatter for method chaining.
Example:
IBytes(1536).WithPrecision(2).String() // "1.50 KiB"
type CommaFormatter ¶
type CommaFormatter[T Number] struct { // contains filtered or unexported fields }
CommaFormatter formats numbers with comma separators for thousands. Use Comma to create a CommaFormatter, then optionally call WithPrecision before calling String to get the formatted result.
func Comma ¶
func Comma[T Number](v T) *CommaFormatter[T]
Comma creates a new CommaFormatter for the given numeric value. The type parameter T can be any integer or floating-point type. By default, integers are displayed without decimals and floats are displayed with their natural precision.
Example:
Comma(int64(1234567)).String() // "1,234,567" Comma(1234567.89).String() // "1,234,567.89" Comma(1234567.89).WithPrecision(1).String() // "1,234,567.9"
func (*CommaFormatter[T]) Format ¶
func (f *CommaFormatter[T]) Format(st fmt.State, verb rune)
Format implements the fmt.Formatter interface for use with printf-style functions. The 'v' and 's' verbs are supported.
Example:
fmt.Printf("%v", Comma(1234567)) // "1,234,567"
func (*CommaFormatter[T]) String ¶
func (f *CommaFormatter[T]) String() string
String formats the number with comma separators. Integer types are formatted without a decimal point. Float types preserve their natural precision unless WithPrecision was called.
func (*CommaFormatter[T]) WithPrecision ¶
func (f *CommaFormatter[T]) WithPrecision(p int) *CommaFormatter[T]
WithPrecision sets the number of decimal places to display. For integers, this adds a decimal point and trailing zeros. Returns the CommaFormatter for method chaining.
Example:
Comma(1234).WithPrecision(2).String() // "1,234.00" Comma(1234.5678).WithPrecision(2).String() // "1,234.57"
Source Files