Version: v1.0.3 Latest Latest Go to latest
Published: Nov 14, 2018 License: MIT

## README ¶

### stdsize

`import "toolman.org/numbers/stdsize"`

#### 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
``````

#### Variables

``````var (
// ErrBadModifier is returned by Parse and ParseBinary if the
// given size modifier is unrecognized.

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

## Documentation ¶

### 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".

### Constants ¶

This section is empty.

### Variables ¶

View Source
```var (
// ErrBadModifier is returned by Parse and ParseBinary if the
// given size modifier is unrecognized.

// 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")
)```

### Functions ¶

This section is empty.

### Types ¶

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