or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

byte-sizes.mdenglish.mdindex.mdnumber-formatting.mdordinals.mdsi-notation.mdtime-formatting.md
tile.json

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) string

Formats 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 format
  • unit - 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) string

Formats a number with an SI prefix and unit, limiting the decimal places to the specified number.

Parameters:

  • input - The number to format
  • decimals - Maximum number of decimal places
  • unit - 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 prefix
  • string - 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 = nil

SI Prefixes Reference

The following SI prefixes are supported:

PrefixSymbolFactorExample
quectoq10^-301 qF = 0.000000000000000000000000000001 F
rontor10^-271 rF = 0.000000000000000000000000001 F
yoctoy10^-241 yF = 0.000000000000000000000001 F
zeptoz10^-211 zF = 0.000000000000000001 F
attoa10^-181 aF = 0.000000000000000001 F
femtof10^-151 fF = 0.000000000000001 F
picop10^-121 pF = 0.000000000001 F
nanon10^-91 nF = 0.000000001 F
microµ10^-61 µF = 0.000001 F
millim10^-31 mF = 0.001 F
(none)10^01 F = 1 F
kilok10^31 kF = 1000 F
megaM10^61 MF = 1000000 F
gigaG10^91 GF = 1000000000 F
teraT10^121 TF = 1000000000000 F
petaP10^151 PF = 1000000000000000 F
exaE10^181 EF = 1000000000000000000 F
zettaZ10^211 ZF = 1000000000000000000000 F
yottaY10^241 YF = 1000000000000000000000000 F
ronnaR10^271 RF = 1000000000000000000000000000 F
quettaQ10^301 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() and IBytes() functions for byte sizes that are more appropriate for that use case.
  • Trailing Zeros: SI() uses Ftoa() internally to remove trailing zeros. Use SIWithDigits() 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".