unit

README

unit

Unit is a library to parse user defined units in go. It was written with sizes in mind, but everything where the numeric part can be converted to an int64 is possible.

It can be used standalone, but also implements the flag interfaces.

Installing

go get -u github.com/rck/unit

Next, include unit in your application:

import "github.com/rck/unit"

Example

package main

import (
	"flag"
	"fmt"
	"log"

	"github.com/rck/unit"
)

func main() {
	size := unit.MustNewUnit(unit.DefaultUnits).MustNewValue(1, unit.None)
	flag.Var(size, "s", "Parse a size")
	flag.Parse()
	fmt.Println(size.Value)

	myUnits := unit.DefaultUnits
	myUnits["kB"] = unit.DefaultUnits["KB"]

	u, err := unit.NewUnit(myUnits)
	if err != nil {
		log.Fatalf("Could not create unit based on mapping: %v\n", err)
	}
	if v, err := u.ValueFromString("+1024K"); err == nil {
		fmt.Println(v.Value, v)
		switch v.ExplicitSign {
		case unit.Positive:
			fmt.Println("Explicit positive sign")
		case unit.Negative:
			fmt.Println("Explicit negative sign")
		case unit.None:
			fmt.Println("No xxplicit sign")
		default:
			fmt.Println("This can not happen :-)")
		}
	}

	// if called with -s 20M, prints:
	// 20971520
	// 1048576 +1M
	// Explicit positive sign
}

LICENSE

This project is licensed under the same terms as u-root.

Documentation

Overview

Package unit implements parsing for string values with units.

Index

• Constants
• Variables
• type Sign
• type Unit
  • func MustNewUnit(m map[string]int64) *Unit
  • func NewUnit(m map[string]int64) (*Unit, error)
  • func (u *Unit) MustNewValue(value int64, explicitSign Sign) *Value
  • func (u *Unit) NewValue(value int64, explicitSign Sign) (*Value, error)
  • func (u *Unit) ValueFromString(str string) (*Value, error)
• type Value
  • func (s Value) Get() interface{}
  • func (s *Value) Set(str string) error
  • func (s Value) String() string
  • func (s *Value) Type() string

Constants

const (

	// K is 1024 byte
	K int64 = 1 << (10 * iota)
	// M is 1024 K
	M
	// G is 1024 M
	G
	// T is 1024 G
	T
	// P is 1024 T
	P
	// E is 1024 P
	E
)

Variables

var DefaultUnits = map[string]int64{
	"B":  1,
	"K":  K,
	"M":  M,
	"G":  G,
	"T":  T,
	"P":  P,
	"E":  E,
	"kB": 1000,
	"KB": 1000,
	"MB": 1000 * 1000,
	"GB": 1000 * 1000 * 1000,
	"TB": 1000 * 1000 * 1000 * 1000,
	"PB": 1000 * 1000 * 1000 * 1000 * 1000,
	"EB": 1000 * 1000 * 1000 * 1000 * 1000 * 1000,
}

DefaultUnits is the default unit mapping as used by many standard cli-tools.

Types

type Sign

type Sign uint8

Sign is the sign associated with a unit's value.

const (
	// None signals that no explicit sign is set.
	None Sign = iota
	// Negative signals that an explicit negative sign is set.
	Negative
	// Positive signals that an explicit positive sign is set.
	Positive
)

type Unit

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

Unit is a map of unit names to conversion multipliers.

There must be a named unit that maps to 1.

The empty string is special: it defines the default unit, i.e., the multiplier applied to input without a unit suffix (see Set). It must alias one of the named units in the mapping. If no default unit is defined, input without a unit suffix is treated as multiplier 1. The default unit is never used for output; String always prints a named unit.

func MustNewUnit

func MustNewUnit(m map[string]int64) *Unit

MustNewUnit is like NewUnit but panics if the mapping 'm' is not valid.

func NewUnit

func NewUnit(m map[string]int64) (*Unit, error)

NewUnit returns a new Unit given a mapping 'm'.

The mapping is copied; later changes to 'm' do not affect the Unit.

func (*Unit) MustNewValue

func (u *Unit) MustNewValue(value int64, explicitSign Sign) *Value

MustNewValue is like NewValue but panics if the new Value could not be generated.

func (*Unit) NewValue

func (u *Unit) NewValue(value int64, explicitSign Sign) (*Value, error)

NewValue returns a Value based on a Unit. It's value is set to "value". "value" is the initial value, an explicit sign can be set, but is usually "None".

func (*Unit) ValueFromString

func (u *Unit) ValueFromString(str string) (*Value, error)

ValueFromString converts the given string to a Value. The string is allowed to have '+'/'-' as prefix, followed by a number, and an optional unit name as defined in its mapping.

type Value

type Value struct {

	// value is the integer value.
	Value int64

	// sign is the explicit sign given by the string converted to the
	// integer.
	ExplicitSign Sign

	// set to false if this is the default value, true if the the option was given
	IsSet bool
	// contains filtered or unexported fields
}

Value is any value that can be represented by a unit.

Value implements flag.Value and flag.Getter.

func (Value) Get

func (s Value) Get() interface{}

Get implements flag.Getter.Get.

func (*Value) Set

func (s *Value) Set(str string) error

Set implements flag.Value.Set.

func (Value) String

func (s Value) String() string

String implements flag.Value.String and fmt.Stringer.

The value is printed using the named unit with the largest multiplier that divides it evenly. If several units share that multiplier, the shortest name is preferred, then the lexicographically smallest one. The default unit "" is never used. The result is deterministic and can be parsed back by Set.

func (*Value) Type

func (s *Value) Type() string

Type implements pflag.Value.Type.