unitconv

Documentation

Overview

Package unitconv implements string conversion functionality for unit prefixes such as those from the SI and IEC standards.

See https://wikipedia.org/wiki/unit_prefix

Index

• Constants
• func AppendPrefix(dst []byte, val float64, m Mode, prec int) (out []byte)
• func FormatPrefix(val float64, m Mode, prec int) (str string)
• func ParsePrefix(str string, m Mode) (val float64, err error)
• type Mode

Examples

• AppendPrefix
• FormatPrefix
• ParsePrefix

Constants

const (
	Kibi = 1 << 10
	Mebi = 1 << 20
	Gibi = 1 << 30
	Tebi = 1 << 40
	Pebi = 1 << 50
	Exbi = 1 << 60
	Zebi = 1 << 70
	Yobi = 1 << 80
)

Prefix factors according to IEC standards.

const (
	Yocto = 1e-24
	Zepto = 1e-21
	Atto  = 1e-18
	Femto = 1e-15
	Pico  = 1e-12
	Nano  = 1e-9
	Micro = 1e-6
	Milli = 1e-3

	Unit = 1e0 // Not a standard SI prefix.

	Kilo  = 1e+3
	Mega  = 1e+6
	Giga  = 1e+9
	Tera  = 1e+12
	Peta  = 1e+15
	Exa   = 1e+18
	Zetta = 1e+21
	Yotta = 1e+24
)

Prefix factors according to SI standards.

Functions

func AppendPrefix

func AppendPrefix(dst []byte, val float64, m Mode, prec int) (out []byte)

AppendPrefix appends the string form of the floating-point number val, as generated by FormatPrefix, to dst and returns the extended buffer.

Example

package main

import (
	"fmt"

	"github.com/dsnet/golib/unitconv"
)

func main() {
	b1 := []byte("Distance from SF to LA: ")
	b1 = unitconv.AppendPrefix(b1, 616379, unitconv.SI, -1)
	b1 = append(b1, 'm')
	fmt.Println(string(b1))

	b2 := []byte("Capacity of a DVD: ")
	b2 = unitconv.AppendPrefix(b2, 4.7*unitconv.Giga, unitconv.IEC, 2)
	b2 = append(b2, 'B')
	fmt.Println(string(b2))

}

Output:

Distance from SF to LA: 616.379km
Capacity of a DVD: 4.38GiB

func FormatPrefix

func FormatPrefix(val float64, m Mode, prec int) (str string)

FormatPrefix converts the floating-point number val to a string, according to the prefix notation specified by mode. The prec specifies the precision used by the numeric portion.

Even if prec is -1, formatting a value and parsing it does not guarantee that the exact value will be returned. It will however be extremely accurate.

It is valid to format +Inf, -Inf, and NaN.

Example

package main

import (
	"fmt"

	"github.com/dsnet/golib/unitconv"
)

func main() {
	s1 := unitconv.FormatPrefix(unitconv.Tebi, unitconv.SI, 3)
	fmt.Printf("1 tebibyte in SI: %sB\n", s1)

	s2 := unitconv.FormatPrefix(unitconv.Tera, unitconv.IEC, 3)
	fmt.Printf("1 terabyte in IEC: %sB\n", s2)

}

Output:

1 tebibyte in SI: 1.100TB
1 terabyte in IEC: 931.323GiB

func ParsePrefix

func ParsePrefix(str string, m Mode) (val float64, err error)

ParsePrefix converts the string str to a floating-point number, according to the prefix notation specified by mode.

It is valid to parse +Inf, -Inf, and NaN.

Example

package main

import (
	"fmt"

	"github.com/dsnet/golib/unitconv"
)

func main() {
	if s, err := unitconv.ParsePrefix("2.99792458E8", unitconv.AutoParse); err == nil {
		fmt.Printf("Speed of light: %.0fm/s\n", s)
	}

	if s, err := unitconv.ParsePrefix("616.379k", unitconv.SI); err == nil {
		fmt.Printf("Distance from LA to SF: %.0fm\n", s)
	}

	if s, err := unitconv.ParsePrefix("32M", unitconv.Base1024); err == nil {
		fmt.Printf("Max FAT12 partition size: %.0fB\n", s)
	}

	if s, err := unitconv.ParsePrefix("1Ti", unitconv.IEC); err == nil {
		fmt.Printf("Number of bytes in tebibyte: %.0fB\n", s)
	}

}

Output:

Speed of light: 299792458m/s
Distance from LA to SF: 616379m
Max FAT12 partition size: 33554432B
Number of bytes in tebibyte: 1099511627776B

Types

type Mode

type Mode int

Mode is the base conversion for strings.

const (
	// AutoParse will parse the input as either the SI, IEC, or regular float
	// notation as accepted by ParseFloat.
	//
	// This is an invalid mode for Append and Format.
	AutoParse Mode = iota

	// SI uses a scaling of 1000x, and uses a single letter symbol to denote
	// the scaling. The prefixes ranges from Yocto (1E-24) to Yotta (1E+24).
	//
	// The output uses SI prefixes, and uses 'k' for Kilo and 'μ' for Micro.
	// The input accepts SI prefixes along with 'k' and 'K' for Kilo and
	// 'μ' and 'u' for Micro.
	// It does not support the Deca, Hecto, Deci, or Centi prefixes.
	SI

	// Base1024 uses a scaling of 1024x, but uses the same prefixes as SI. This
	// is a non-standard prefix notation and exists because many legacy systems
	// unfortunately operate in this way.
	//
	// The output uses SI prefixes, but uses 'K' for Kilo and 'u' for Micro.
	// The input accepts SI prefixes along with 'k' and 'K' for Kilo and
	// 'μ' and 'u' for Micro. It also accepts IEC notation.
	Base1024

	// IEC uses a scaling of 1024x, and uses a two-letter symbol to denote the
	// scaling in a system similar to SI. Instead of Kilo denoted as 'k', it
	// uses Kibi denoted as 'Ki'. The prefixes ranges from Unit (1) to Yobi
	// (1<<80). Representing values less than 1 will not use any of the divisor
	// prefixes. IEC notation is easy to identify since the prefix symbols
	// always end with the letter 'i'.
	//
	// The output uses IEC prefixes that are Unit and greater.
	// The input accepts IEC prefixes only.
	IEC
)

These are the different modes for Prefix string conversion.