bitty

package module
v0.4.3-0...-f20c671 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 3, 2021 License: Apache-2.0 Imports: 5 Imported by: 0

README

Bitty

Build Status Go Report Card codecov

Bitty is a memory unit conversion library that makes working with multiple sizes and SI/IEC standards straight forward. It is based on unit ecapsulation, immutability, plugability, and testability: the idea that each unit should know how to operate with other valid units idempotently; every unit function returns a new unit or value, instead of changing itself; each unit implements interfaces so that it's easy to plug in new unit types (which also makes testing new unit types straight forward).

Features

Standards Compliance
Mathematics
  • Adding different units against each other
  • Subtracting units from each other
  • Multiplying units against each other
  • Dividing units from each other
Conversions
  • Unit conversions
  • Standard conversions
Helpers
  • Unit parsing
  • Finding a specific unit

Documentation

Overview

Package bitty conforms to IEC and SI Standards Conversions taken from SI Brochure 9, EN, Chapter 3, page 143 (145) https://www.bipm.org/utils/common/pdf/si-brochure/SI-Brochure-9.pdf

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrUnitSymbolNotSupported       = errors.New("unit symbol not supported")
	ErrUnitSymbolNotSupportedf      = string(ErrUnitSymbolNotSupported.Error() + ": %s")
	ErrUnitSymbolEmptyNotSupportedf = errors.Errorf(ErrUnitSymbolNotSupported.Error() + ": empty symbol")
	ErrUnitExponentNotSupported     = errors.New("unit exponent not supported")
	ErrUnitExponentNotSupportedf    = string(ErrUnitExponentNotSupported.Error() + ": %s")
	ErrUnitStandardNotSupported     = errors.New("unit standard not supported")
	ErrUnitStandardNotSupportedf    = string(ErrUnitStandardNotSupported.Error() + ": %s")
	ErrUnitCouldNotBeParsed         = errors.New("unit could not be parsed")
	ErrUnitCouldNotBeParsedf        = string(ErrUnitCouldNotBeParsed.Error() + ": %s")
)

Error messages for Units

Functions

func BytesToUnitSymbolSize 

func BytesToUnitSymbolSize(std UnitStandard, sym UnitSymbol, size float64) float64

BytesToUnitSymbolSize converts bytes to the best unit size as a float64

func FindExponentBySymbol 

func FindExponentBySymbol(sym UnitSymbol) (int, bool)

FindExponentBySymbol takes a symbol and returns the exponent

func NewErrUnitCouldNotBeParsed 

func NewErrUnitCouldNotBeParsed(s string) error

NewErrUnitCouldNotBeParsed returns an error formatted for a given Unit

func NewErrUnitStandardNotSupported 

func NewErrUnitStandardNotSupported(s UnitStandard) error

NewErrUnitStandardNotSupported returns an error formatted for a given UnitStandard

func NewErrUnitSymbolNotSupported 

func NewErrUnitSymbolNotSupported(s UnitSymbol) error

NewErrUnitSymbolNotSupported returns an error formatted for a given UnitSymbol

func UnitSymbolToByteSize 

func UnitSymbolToByteSize(std UnitStandard, sym UnitSymbol, size float64) float64

UnitSymbolToByteSize converts the size from one unit into bytes

func ValidateSymbol 

func ValidateSymbol(sym UnitSymbol) bool

ValidateSymbol checks that a symbol is valid

func ValidateSymbols 

func ValidateSymbols(l, r UnitSymbol) (bool, bool)

ValidateSymbols validates all symbols, returning a tuple of booleans

Types

type BaseUnitSymbolPair 

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

BaseUnitSymbolPair represents the bit and byte pairs

func (*BaseUnitSymbolPair) Exponent 

func (b *BaseUnitSymbolPair) Exponent() int

Exponent returns the exponent of a BaseUnitSymbolPair: 0

func (*BaseUnitSymbolPair) Greatest 

func (b *BaseUnitSymbolPair) Greatest() UnitSymbol

Greatest returns the greatest UnitSymbol of a BaseUnitSymbolPair: a Byte

func (*BaseUnitSymbolPair) Least 

func (b *BaseUnitSymbolPair) Least() UnitSymbol

Least returns the least UnitSymbol of a BaseUnitSymbolPair: a Bit

func (*BaseUnitSymbolPair) Standard 

func (b *BaseUnitSymbolPair) Standard() UnitStandard

Standard returns the UnitStandard of a BaseUnitSymbolPair if it exists or SI

type Calculator 

type Calculator interface {
	// Add attempts to add one Unit to another
	Add(Unit) Unit
	// Subtract attempts to subtract one Unit from another
	Subtract(Unit) Unit
	// Multiply attempts to multiply one Unit by another
	Multiply(Unit) Unit
	// Divide attempts to divide one Unit from another
	Divide(Unit) Unit
}

Calculator enables Units to be calculated against each other All returns are diminshing or increasing UnitSymbol measurements as defined by the SI and IEC

type IECUnit 

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

IECUnit handles binary units as dictated by SI Standards

func NewIECUnit 

func NewIECUnit(size float64, sym UnitSymbol) (*IECUnit, error)

NewIECUnit returns a *IECUnit with the proper exponent included

Example 
a, _ := NewIECUnit(10.0, Mib)
b, _ := NewIECUnit(1.0, "GiB")
_, cerr := NewIECUnit(3.0, "")
_, derr := NewIECUnit(32.0, "fooBar")
fmt.Printf("%v\n", a)
fmt.Printf("%v\n", b)
fmt.Printf("%v\n", cerr)
fmt.Printf("%v\n", derr)

Output:

&{10 Mib 2}
&{1 GiB 3}
unit symbol not supported: empty symbol
unit symbol not supported: fooBar

func (*IECUnit) Add 

func (u *IECUnit) Add(unit Unit) Unit

Add attempts to add one Unit to another

Example 
// Test the same byte symbol
a, _ := NewIECUnit(2, MiB)
b, _ := NewIECUnit(2, MiB)
c, ok := a.Add(b).(*IECUnit)
if !ok {
	panic(fmt.Errorf("Unit not *IECUnit: %v", c))
}
fmt.Printf(
	"%.f %s + %.f %s = %.f %s\n",
	a.Size(), a.Symbol(),
	b.Size(), b.Symbol(),
	c.Size(), c.Symbol(),
)

Output:

2 MiB + 2 MiB = 4 MiB

func (*IECUnit) BitSize 

func (u *IECUnit) BitSize() float64

BitSize returns the size of the Unit measured in bits

Example 
a, _ := NewIECUnit(10.0, MiB)
b, _ := NewIECUnit(10.0, Mib)
fmt.Printf("%.f\n", a.BitSize())
fmt.Printf("%.f\n", b.BitSize())

Output:

83886080
10485760

func (*IECUnit) ByteSize 

func (u *IECUnit) ByteSize() float64

ByteSize returns the size of the Unit measured in bytes

Example 
a, _ := NewIECUnit(10.0, MiB)
b, _ := NewIECUnit(10.0, Mib)
fmt.Printf("%.f\n", a.ByteSize())
fmt.Printf("%.f\n", b.ByteSize())

Output:

10485760
1310720

func (*IECUnit) Divide 

func (u *IECUnit) Divide(unit Unit) Unit

Divide attempts to divide one Unit by another

func (*IECUnit) Exponent 

func (u *IECUnit) Exponent() int

Exponent returns the exponent of a IECUnit

func (*IECUnit) Multiply 

func (u *IECUnit) Multiply(unit Unit) Unit

Multiply attempts to multiply one Unit by another

func (*IECUnit) Size 

func (u *IECUnit) Size() float64

Size returns the size of an IECUnit

func (*IECUnit) SizeInUnit 

func (u *IECUnit) SizeInUnit(symbol UnitSymbol) float64

SizeInUnit returns the size of the Unit measured in an arbitrary UnitSymbol from Bit up to YiB or YB

Example 
a, _ := NewIECUnit(10.0, MiB)
inKiB := a.SizeInUnit(KiB)
inGiB := a.SizeInUnit(GiB)
inMib := a.SizeInUnit(Mib)
fmt.Println(inKiB, inGiB, inMib)

Output:

10240 0.009765625 80

func (*IECUnit) Standard 

func (u *IECUnit) Standard() UnitStandard

Standard returns the UnitStandard of a IECUnit: IEC

func (*IECUnit) Subtract 

func (u *IECUnit) Subtract(unit Unit) Unit

Subtract attempts to subtract one Unit from another

Example 
var (
	c  *IECUnit
	ok bool
)
// Test the same byte symbol
a, _ := NewIECUnit(10, GiB)
b, _ := NewIECUnit(10.023, GiB)
c, ok = a.Subtract(b).(*IECUnit)
if !ok {
	panic(fmt.Errorf("Unit not *IECUnit: %v", c))
}
fmt.Printf(
	"%.3f %s - %.3f %s = %.3f %s\n",
	a.size, a.symbol,
	b.size, b.symbol,
	c.size, c.symbol,
)

Output:

10.000 GiB - 10.023 GiB = -23.552 MiB

func (*IECUnit) Symbol 

func (u *IECUnit) Symbol() UnitSymbol

Symbol returns the UnitSymbol of a IECUnit

type IECUnitSymbolPair 

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

IECUnitSymbolPair represents a base 2 binary unit symbol pair as defined by the 9th edition SI standard

func (*IECUnitSymbolPair) Exponent 

func (pair *IECUnitSymbolPair) Exponent() int

Exponent returns the exponent of a IECUnitSymbolPair

func (*IECUnitSymbolPair) Greatest 

func (pair *IECUnitSymbolPair) Greatest() UnitSymbol

Greatest returns the greatest UnitSymbol of a IECUnitSymbolPair

func (*IECUnitSymbolPair) Least 

func (pair *IECUnitSymbolPair) Least() UnitSymbol

Least returns the least UnitSymbol of a IECUnitSymbolPair

func (*IECUnitSymbolPair) Standard 

func (pair *IECUnitSymbolPair) Standard() UnitStandard

Standard returns the UnitStandard of a IECUnitSymbolPair: IEC

type SIUnit 

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

SIUnit handles binary units as dictated by SI Standards

func NewSIUnit 

func NewSIUnit(size float64, sym UnitSymbol) (*SIUnit, error)

NewSIUnit returns a *SIUnit with the proper exponent included

Example 
a, _ := NewSIUnit(10.0, MB)
fmt.Printf("%v\n", a)

Output:

&{10 MB 6}

func (*SIUnit) Add 

func (u *SIUnit) Add(unit Unit) Unit

Add attempts to add one Unit to another

Example 
// Test the same byte symbol
a, _ := NewSIUnit(2, MB)
b, _ := NewSIUnit(2, MB)
c, ok := a.Add(b).(*SIUnit)
if !ok {
	panic(fmt.Errorf("Unit not *SIUnit: %v", c))
}
fmt.Printf(
	"%.f %s + %.f %s = %.f %s\n",
	a.Size(), a.Symbol(),
	b.Size(), b.Symbol(),
	c.Size(), c.Symbol(),
)

Output:

2 MB + 2 MB = 4 MB

func (*SIUnit) BitSize 

func (u *SIUnit) BitSize() float64

BitSize returns the size of the Unit measured in bits

func (*SIUnit) ByteSize 

func (u *SIUnit) ByteSize() float64

ByteSize returns the size of the Unit measured in bytes

Example 
a, _ := NewSIUnit(10.0, kB)
fmt.Printf("%.f\n", a.ByteSize())

Output:

10000

func (*SIUnit) Divide 

func (u *SIUnit) Divide(unit Unit) Unit

Divide attempts to divide one Unit by another

func (*SIUnit) Exponent 

func (u *SIUnit) Exponent() int

Exponent returns the exponent of a SIUnit

func (*SIUnit) Multiply 

func (u *SIUnit) Multiply(unit Unit) Unit

Multiply attempts to multiply one Unit by another

func (*SIUnit) Size 

func (u *SIUnit) Size() float64

Size returns the size of an SIUnit

func (*SIUnit) SizeInUnit 

func (u *SIUnit) SizeInUnit(symbol UnitSymbol) float64

SizeInUnit returns the size of the Unit measured in an arbitrary UnitSymbol from Bit up to YiB or YB

func (*SIUnit) Standard 

func (u *SIUnit) Standard() UnitStandard

Standard returns the UnitStandard of a SIUnit: SI

func (*SIUnit) Subtract 

func (u *SIUnit) Subtract(unit Unit) Unit

Subtract attempts to subtract one Unit from another

Example 
var (
	c  *SIUnit
	ok bool
)
// Test the same byte symbol
a, _ := NewSIUnit(10, MB)
b, _ := NewSIUnit(10.023, MB)
c, ok = a.Subtract(b).(*SIUnit)
if !ok {
	panic(fmt.Errorf("Unit not *SIUnit: %v", c))
}
fmt.Printf(
	"%.3f %s - %.3f %s = %.3f %s\n",
	a.size, a.symbol,
	b.size, b.symbol,
	c.size, c.symbol,
)

Output:

10.000 MB - 10.023 MB = -23.000 kB

func (*SIUnit) Symbol 

func (u *SIUnit) Symbol() UnitSymbol

Symbol returns the UnitSymbol of a SIUnit

type SIUnitSymbolPair 

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

SIUnitSymbolPair represents a base 10 decimal unit symbol pair as defined by the 9th edition SI standard

func (*SIUnitSymbolPair) Exponent 

func (pair *SIUnitSymbolPair) Exponent() int

Exponent returns the exponent of a SIUnitSymbolPair

func (*SIUnitSymbolPair) Greatest 

func (pair *SIUnitSymbolPair) Greatest() UnitSymbol

Greatest returns the greatest UnitSymbol of a SIUnitSymbolPair

func (*SIUnitSymbolPair) Least 

func (pair *SIUnitSymbolPair) Least() UnitSymbol

Least returns the least UnitSymbol of a SIUnitSymbolPair

func (*SIUnitSymbolPair) Standard 

func (pair *SIUnitSymbolPair) Standard() UnitStandard

Standard returns the UnitStandard of a SIUnitSymbolPair: SI

type Sizer 

type Sizer interface {
	// Size returns the size of the Unit
	Size() float64
	// BitSize returns the size of the Unit measured in bits
	BitSize() float64
	// ByteSize returns the size of the Unit measured in bytes
	ByteSize() float64
	// SizeInUnit returns the size of the Unit measured in an arbitrary
	// UnitSymbol from Bit up to YiB or YB
	SizeInUnit(UnitSymbol) float64
}

Sizer enables Unit to get a size measured by bit, byte, or arbitrary data Unit kind

type Symbolic 

type Symbolic interface {
	// Standard returns the standard for the unit as defined by the SI brochure,
	// 9th Edition, page 145:
	// 	https://www.bipm.org/utils/common/pdf/si-brochure/SI-Brochure-9.pdf
	Standard() UnitStandard
	// Exponent returns the supported exponent as an int
	// To calculate the value from the standard, symbol, and size the formulas
	// are:
	// 	- Given the Standard is SI, value as v is equal to (10^e)size
	// 	- Given the Standard is IEC, value as v is equal to (2^(e*10))size
	Exponent() int
	// Symbol returns the supported symbol as a UnitSymbol
	Symbol() UnitSymbol
}

Symbolic enables Unit to provide a standard, exponent, and symbol

type Unit 

type Unit interface {
	Symbolic
	Sizer
	Calculator
}

Unit enables Unit kinds to interact with each other

func AddUnits 

func AddUnits(lu, ru Unit) (Unit, error)

AddUnits takes two units with valid symbols, sums them, then returns a new unit AddUnits will always default to the left unit's symbol and exponent

func ConvertUnitStd 

func ConvertUnitStd(u Unit, std UnitStandard) (Unit, error)

ConvertUnitStd takes a unit from one standard and converts it to another

func NewUnit 

func NewUnit(std UnitStandard, size float64, sym UnitSymbol) (Unit, error)

NewUnit takes a UnitStandard, float64, and UnitSymbol, returning a valid Unit

func Parse 

func Parse(s string) (Unit, error)

Parse parses a string representation of a unit size in the format of "<size><unit symbol>" or "<size> <unit symbol>" in order to instantiate and return a Unit with the correct standard, exponent, size, and symbol

func SubtractUnits 

func SubtractUnits(lu, ru Unit) (Unit, error)

SubtractUnits takes two units with valid symbols, subtracts them, then returns a new unit SubtractUnits will always default to the left unit's symbol and exponent

type UnitStandard 

type UnitStandard int

UnitStandard represents a standard for unit measurement. Currently SI 9th edition is the supported standard, with SI notation for IEC binary and decimal formats 

const (
	SI UnitStandard = iota
	IEC
)

Unit Standard enums

func FindStandardBySymbol 

func FindStandardBySymbol(sym UnitSymbol) (UnitStandard, bool)

FindStandardBySymbol takes a unit symbol, searches for a symbol pair that matches, and returns the standard for that pair

type UnitSymbol 

type UnitSymbol string

UnitSymbol represents the measurement symbol of a binary measurement as dictated by the SI 

const (
	Bit  UnitSymbol = "Bit"
	Byte UnitSymbol = "Byte"
	Kib  UnitSymbol = "Kib"
	Mib  UnitSymbol = "Mib"
	Gib  UnitSymbol = "Gib"
	Tib  UnitSymbol = "Tib"
	Pib  UnitSymbol = "Pib"
	Eib  UnitSymbol = "Eib"
	Zib  UnitSymbol = "Zib"
	Yib  UnitSymbol = "Yib"
	KiB  UnitSymbol = "KiB"
	MiB  UnitSymbol = "MiB"
	GiB  UnitSymbol = "GiB"
	TiB  UnitSymbol = "TiB"
	PiB  UnitSymbol = "PiB"
	EiB  UnitSymbol = "EiB"
	ZiB  UnitSymbol = "ZiB"
	YiB  UnitSymbol = "YiB"

	Mb UnitSymbol = "Mb"
	Gb UnitSymbol = "Gb"
	Tb UnitSymbol = "Tb"
	Pb UnitSymbol = "Pb"
	Eb UnitSymbol = "Eb"
	Zb UnitSymbol = "Zb"
	Yb UnitSymbol = "Yb"

	MB UnitSymbol = "MB"
	GB UnitSymbol = "GB"
	TB UnitSymbol = "TB"
	PB UnitSymbol = "PB"
	EB UnitSymbol = "EB"
	ZB UnitSymbol = "ZB"
	YB UnitSymbol = "YB"
)

SI symbols for binary measurements including notation for former IEC measurements

func FindGreatestUnitSymbol 

func FindGreatestUnitSymbol(std UnitStandard, exp int) (UnitSymbol, bool)

FindGreatestUnitSymbol finds the greatest of two unit symbols for a given exponent by standard.

Currently, if no symbol pair is found, we attempt to recursively find the floor exponent in which one is found, or return Byte. This is mostly to support base 10 decimal values where the exponents do not flow smoothly from 1-8 (like base 2 does).

func FindLeastUnitSymbol 

func FindLeastUnitSymbol(std UnitStandard, exp int) (UnitSymbol, bool)

FindLeastUnitSymbol finds the least of two unit symbols for a given exponent by standard.

Currently, if no symbol pair is found, we attempt to recursively find the floor exponent in which one is found, or return Bit. This is mostly to support base 10 decimal values where the exponents do not flow smoothly from 1-8 (like base 2 does).

type UnitSymbolPair 

type UnitSymbolPair interface {
	Standard() UnitStandard
	Exponent() int
	Least() UnitSymbol
	Greatest() UnitSymbol
}

UnitSymbolPair holds the least and greatest UnitSymbol for a given standard and exponent

func FindUnitSymbolPairByExponent 

func FindUnitSymbolPairByExponent(std UnitStandard, exp int) (UnitSymbolPair, bool)

FindUnitSymbolPairByExponent takes a UnitStandard and an exponent in order to find and return the UnitSymbolPair for that standard and exponent, or false if the UnitSymbolPair cannot be found.

func FindUnitSymbolPairBySymbol 

func FindUnitSymbolPairBySymbol(std UnitStandard, sym UnitSymbol) (UnitSymbolPair, bool)

FindUnitSymbolPairBySymbol takes a UnitStandard and a symbol in order to find and return the UnitSymbolPair for that standard and symbol, or false if the UnitSymbolPair cannot be found.

func NewBaseUnitSymbolPair 

func NewBaseUnitSymbolPair(std UnitStandard) UnitSymbolPair

NewBaseUnitSymbolPair takes a UnitStandard and returns a new UnitSymbolPair

func NewIECUnitSymbolPair 

func NewIECUnitSymbolPair(l, r UnitSymbol, e int) UnitSymbolPair

NewIECUnitSymbolPair takes a UnitStandard and returns a new UnitSymbolPair

func NewSIUnitSymbolPair 

func NewSIUnitSymbolPair(l, r UnitSymbol, e int) UnitSymbolPair

NewSIUnitSymbolPair takes a UnitStandard and returns a new UnitSymbolPair

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.