tessl/golang-github-com-dustin--go-humanize
Humane Units - functions for helping humanize times and sizes
si-notation.mddocs/
SI Notation
Formats numbers with SI (International System of Units) prefixes like p (pico), n (nano), µ (micro), m (milli), k (kilo), M (mega), G (giga), T (tera), etc., and parses SI notation strings back to numeric values.
Import
import "github.com/dustin/go-humanize"Formatting with SI Prefixes
SI
func SI(input float64, unit string) stringFormats a number with an appropriate SI prefix and unit. Automatically selects the best SI prefix to keep the number in a readable range. Uses Ftoa internally to remove trailing zeros.
Parameters:
input- The number to formatunit- The base unit (e.g., "B" for bytes, "F" for farads, "m" for meters)
Returns: String with SI prefix and unit (e.g., "2.23 nM", "1 MB")
Example:
humanize.SI(1000000, "B") // "1 MB"
humanize.SI(0.00000000223, "M") // "2.23 nM"
humanize.SI(1500, "m") // "1.5 km"
humanize.SI(0.001, "A") // "1 mA"
humanize.SI(1000000000000, "Hz") // "1 THz"SIWithDigits
func SIWithDigits(input float64, decimals int, unit string) stringFormats a number with an SI prefix and unit, limiting the decimal places to the specified number.
Parameters:
input- The number to formatdecimals- Maximum number of decimal placesunit- The base unit
Returns: String with SI prefix, limited decimals, and unit
Example:
humanize.SIWithDigits(1000000, 0, "B") // "1 MB"
humanize.SIWithDigits(1234567, 2, "B") // "1.23 MB"
humanize.SIWithDigits(0.00000000223, 2, "F") // "2.23 nF"
humanize.SIWithDigits(1234.5678, 1, "m") // "1.2 km"ComputeSI
func ComputeSI(input float64) (float64, string)Computes the most appropriate SI prefix for a number and returns both the adjusted value and the prefix string.
Parameters:
input- The number to analyze
Returns:
float64- The value adjusted to the SI prefix range (typically between 1 and 1000)string- The SI prefix (e.g., "p", "n", "µ", "m", "", "k", "M", "G", "T")
Example:
value, prefix := humanize.ComputeSI(1000000)
// value = 1.0, prefix = "M"
value, prefix := humanize.ComputeSI(0.00000000223)
// value = 2.23, prefix = "p"
value, prefix := humanize.ComputeSI(750)
// value = 750, prefix = "" (no prefix needed)
// Use the results to format with a custom unit
fmt.Printf("%.2f %sW", value, prefix) // "750.00 W" or "1.00 MW"Parsing SI Notation
ParseSI
func ParseSI(input string) (float64, string, error)Parses an SI notation string and extracts the numeric value and base unit.
Parameters:
input- String with SI prefix and unit (e.g., "2.23 pF", "1.5 km")
Returns:
float64- The numeric value expanded from the SI prefixstring- The base unit (without prefix)error- Error if parsing fails
Example:
value, unit, err := humanize.ParseSI("2.23 pF")
// value = 2.23e-12, unit = "F", err = nil
value, unit, err := humanize.ParseSI("1.5 km")
// value = 1500.0, unit = "m", err = nil
value, unit, err := humanize.ParseSI("100 MB")
// value = 100000000.0, unit = "B", err = nil
value, unit, err := humanize.ParseSI("5.5 mA")
// value = 0.0055, unit = "A", err = nilSI Prefixes Reference
The following SI prefixes are supported:
| Prefix | Symbol | Factor | Example |
|---|---|---|---|
| quecto | q | 10^-30 | 1 qF = 0.000000000000000000000000000001 F |
| ronto | r | 10^-27 | 1 rF = 0.000000000000000000000000001 F |
| yocto | y | 10^-24 | 1 yF = 0.000000000000000000000001 F |
| zepto | z | 10^-21 | 1 zF = 0.000000000000000001 F |
| atto | a | 10^-18 | 1 aF = 0.000000000000000001 F |
| femto | f | 10^-15 | 1 fF = 0.000000000000001 F |
| pico | p | 10^-12 | 1 pF = 0.000000000001 F |
| nano | n | 10^-9 | 1 nF = 0.000000001 F |
| micro | µ | 10^-6 | 1 µF = 0.000001 F |
| milli | m | 10^-3 | 1 mF = 0.001 F |
| (none) | 10^0 | 1 F = 1 F | |
| kilo | k | 10^3 | 1 kF = 1000 F |
| mega | M | 10^6 | 1 MF = 1000000 F |
| giga | G | 10^9 | 1 GF = 1000000000 F |
| tera | T | 10^12 | 1 TF = 1000000000000 F |
| peta | P | 10^15 | 1 PF = 1000000000000000 F |
| exa | E | 10^18 | 1 EF = 1000000000000000000 F |
| zetta | Z | 10^21 | 1 ZF = 1000000000000000000000 F |
| yotta | Y | 10^24 | 1 YF = 1000000000000000000000000 F |
| ronna | R | 10^27 | 1 RF = 1000000000000000000000000000 F |
| quetta | Q | 10^30 | 1 QF = 1000000000000000000000000000000 F |
Common Use Cases
Electronic Component Values
capacitance := 0.00000001 // farads
fmt.Printf("Capacitance: %s", humanize.SI(capacitance, "F"))
// Output: "Capacitance: 10 nF"
resistance := 4700.0 // ohms
fmt.Printf("Resistance: %s", humanize.SI(resistance, "Ω"))
// Output: "Resistance: 4.7 kΩ"Physical Measurements
distance := 0.000042 // meters
fmt.Printf("Distance: %s", humanize.SI(distance, "m"))
// Output: "Distance: 42 µm"
frequency := 2400000000.0 // hertz
fmt.Printf("Frequency: %s", humanize.SI(frequency, "Hz"))
// Output: "Frequency: 2.4 GHz"Data Rates
bitrate := 1000000000.0 // bits per second
fmt.Printf("Speed: %s", humanize.SI(bitrate, "bps"))
// Output: "Speed: 1 Gbps"Parsing User Input
input := "100 MHz"
freq, unit, err := humanize.ParseSI(input)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Frequency: %.0f %s", freq, unit)
// Output: "Frequency: 100000000 Hz"Custom Formatting with ComputeSI
power := 0.0025 // watts
value, prefix := humanize.ComputeSI(power)
// Custom formatting with specific decimal places
fmt.Printf("Power consumption: %.1f %sW", value, prefix)
// Output: "Power consumption: 2.5 mW"
// Or use with SIWithDigits for automatic handling
fmt.Printf("Power consumption: %s",
humanize.SIWithDigits(power, 1, "W"))
// Output: "Power consumption: 2.5 mW"Notes
- Not for Byte Sizes: While technically you can use SI notation for bytes (e.g., "MB"), the package provides dedicated
Bytes()andIBytes()functions for byte sizes that are more appropriate for that use case. - Trailing Zeros:
SI()usesFtoa()internally to remove trailing zeros. UseSIWithDigits()for explicit control over decimal places. - Case Sensitivity: SI prefixes are case-sensitive. "M" (mega) is different from "m" (milli).
- Unicode: The micro prefix is represented as "µ" (U+00B5), not "u".
Install with Tessl CLI
npx tessl i tessl/golang-github-com-dustin--go-humanize