toolman.org/numbers/stdsize

stdsize

import "toolman.org/numbers/stdsize"

• Overview
• Install
• Index

Overview

Package stdsize provides the integer type "Value" that may be created or displayed using human-readable strings. For example, "2Ki" gets parsed as 2048 while the numeric value of 5*1000*1000 (i.e. 5 million) is displayed as "5M".

Install

  go get toolman.org/numbers/stdsize

Index

• Variables
• type Value
  • func Parse(s string) (Value, error)
  • func ParseBinary(s string) (Value, error)
  • func (v Value) Format(f fmt.State, c rune)

Package files

format.go parse.go parts.go units.go value.go

Variables

var (
    // ErrBadModifier is returned by Parse and ParseBinary if the
    // given size modifier is unrecognized.
    ErrBadModifier = errors.New("invalid size modifier")

    // ErrNotInteger is returned by Parse and ParseBinary if no
    // size modifier is provided and the given numeric value is
    // not an integer.
    ErrNotInteger = errors.New("bare size values must be integers")
)

type Value

type Value int64

Value is a standard size value as returned by Parse or ParseBinary. It also provides a custom formatter for displaying human-readable values.

const (
    Kilo Value = 1000        // 10^3
    Mega Value = Kilo * Kilo // 10^6
    Giga Value = Mega * Kilo // 10^9
    Tera Value = Giga * Kilo // 10^12
    Peta Value = Tera * Kilo // 10^15
)

Constants for common decimal (i.e. power of 10) values.

const (
    Kibi Value = 1 << (10 * (iota + 1)) // 2^10
    Mibi                                // 2^20
    Gibi                                // 2^30
    Tebi                                // 2^40
    Pebi                                // 2^50
)

Constants for common binary (i.e. power of 2) values.

func Parse

func Parse(s string) (Value, error)

Parse converts the size designation s to an integer Value. A size designation is specified as any (real) numeric value, either positive or negative, followed by a size modifier.

The following modifiers are supported:

Decimal     Binary
--------    --------
K: 10^3     Ki: 2^10
M: 10^6     Mi: 2^20
G: 10^9     Gi: 2^30
T: 10^12    Ti: 2^40
P: 10^15    Pi: 2^50

For example, "1K" is 1000, "1Ki" is 1024, and "2.5Ki" is 2048 + 512 or 2560.

If no size modifier is provided then the numeric value must be an integer, otherwise Parse returns ErrNotInteger.

If the given size modifier is unrecognized, Parse returns ErrBadModifier.

If the numeric value is unparsable, then Parse returns an error of type *strconv.NumError.

func ParseBinary

func ParseBinary(s string) (Value, error)

ParseBinary is similar to Parse except all size modifiers are assumed to be binary. In other words, both "K" and "Ki" are interpreted as 2^10.

func (Value) Format

func (v Value) Format(f fmt.State, c rune)

Format implements fmt.Formatter to provide custom, printf style formatting for Values. It is not intended to be called directly.