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 unit that maps to 1.

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'.

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.

func (*Value) Type

func (s *Value) Type() string

Type implements pflag.Value.Type.