human

type Bytes ¶

type Bytes uint64

Bytes represents a number of bytes.

The type support parsing values in formats like:

42 KB
8Gi
1.5KiB
...

Two models are supported, using factors of 1000 and factors of 1024 via units like KB, MB, GB for the former, or Ki, Mi, MiB for the latter.

In the current implementation, formatting is always done in factors of 1024, using units like Ki, Mi, Gi etc...

Values may be decimals when using units larger than B. Partial bytes cannot be represnted (e.g. 0.5B is not supported).

const (
	B Bytes = 1

	KB Bytes = 1000 * B
	MB Bytes = 1000 * KB
	GB Bytes = 1000 * MB
	TB Bytes = 1000 * GB
	PB Bytes = 1000 * TB

	KiB Bytes = 1024 * B
	MiB Bytes = 1024 * KiB
	GiB Bytes = 1024 * MiB
	TiB Bytes = 1024 * GiB
	PiB Bytes = 1024 * TiB
)

func ParseBytes(s string) (Bytes, error)

func (b Bytes) MarshalJSON() ([]byte, error)

func (b Bytes) MarshalText() ([]byte, error)

func (b Bytes) MarshalYAML() (interface{}, error)

func (b Bytes) String() string

func (b *Bytes) UnmarshalJSON(j []byte) error

func (b *Bytes) UnmarshalText(t []byte) error

func (b *Bytes) UnmarshalYAML(y *yaml.Node) error

type Count ¶

type Count float64

Count represents a count without a unit.

The type supports parsing and formatting values like:

1234
10 K
1.5M
...

const (
	K Count = 1000
	M Count = 1000 * K
	G Count = 1000 * M
	T Count = 1000 * G
	P Count = 1000 * T
)

func ParseCount(s string) (Count, error)

func (c Count) MarshalJSON() ([]byte, error)

func (c Count) MarshalText() ([]byte, error)

func (c Count) MarshalYAML() (interface{}, error)

func (c Count) String() string

func (c *Count) UnmarshalJSON(b []byte) error

func (c *Count) UnmarshalText(b []byte) error

func (c *Count) UnmarshalYAML(y *yaml.Node) error

type Duration ¶

type Duration time.Duration

Duration is based on time.Duration, but supports parsing and formatting more human-friendly representations.

Here are examples of supported values:

1d
4 weeks
...

The current implementation does not support decimal values, however, contributions are welcome to add this feature.

Time being what it is, months and years are hard to represent because their durations vary in unpredictable ways. This is why the package only exposes constants up to a 1 week duration. For the sake of accuracy, years and months are always represented relative to a given date. Technically, leap seconds can cause any unit above the second to be variable, but in order to remain mentaly sane, we chose to ignore this detail in the implementation of this package.

const (
	Nanosecond  Duration = 1
	Microsecond Duration = 1000 * Nanosecond
	Millisecond Duration = 1000 * Microsecond
	Second      Duration = 1000 * Millisecond
	Minute      Duration = 60 * Second
	Hour        Duration = 60 * Minute
	Day         Duration = 24 * Hour
	Week        Duration = 7 * Day
)

func ParseDuration(s string) (Duration, error)

func ParseDurationUntil(s string, now time.Time) (Duration, error)

func (d Duration) Days() int

func (d Duration) Hours() int

func (d Duration) MarshalJSON() ([]byte, error)

func (d Duration) MarshalText() ([]byte, error)

func (d Duration) MarshalYAML() (interface{}, error)

func (d Duration) Microseconds() int

func (d Duration) Milliseconds() int

func (d Duration) Minutes() int

func (d Duration) Months(until time.Time) int

func (d Duration) Nanoseconds() int

func (d Duration) Seconds() int

func (d Duration) String() string

func (d Duration) Text(until time.Time) string

func (d *Duration) UnmarshalJSON(b []byte) error

func (d *Duration) UnmarshalText(b []byte) error

func (d *Duration) UnmarshalYAML(y *yaml.Node) error

func (d Duration) Weeks() int

func (d Duration) Years(until time.Time) int

type Number ¶

type Number float64

Number is similar to Count, but supports values with separators for readability purposes.

The type supports parsing and formatting values likes:

123
1.5
2,000,000
...

func ParseNumber(s string) (Number, error)

func (n Number) MarshalJSON() ([]byte, error)

func (n Number) MarshalText() ([]byte, error)

func (n Number) MarshalYAML() (interface{}, error)

func (n Number) String() string

func (n *Number) UnmarshalJSON(b []byte) error

func (n *Number) UnmarshalText(b []byte) error

func (n *Number) UnmarshalYAML(y *yaml.Node) error

type Rate ¶

type Rate float64

Rate represents a count devided by a unit of time.

The type supports parsing and formatting values like:

200/s
1 / minute
0.5/week
...

Rate values are always stored in their per-second form in Go programs, and properly converted during parsing and formatting.

const (
	PerNanosecond  Rate = 1 / Rate(Nanosecond)
	PerMicrosecond Rate = 1 / Rate(Microsecond)
	PerMillisecond Rate = 1 / Rate(Millisecond)
	PerSecond      Rate = 1 / Rate(Second)
	PerMinute      Rate = 1 / Rate(Minute)
	PerHour        Rate = 1 / Rate(Hour)
	PerDay         Rate = 1 / Rate(Day)
	PerWeek        Rate = 1 / Rate(Week)
)

func ParseRate(s string) (Rate, error)

func (r Rate) MarshalJSON() ([]byte, error)

func (r Rate) MarshalText() ([]byte, error)

func (r Rate) MarshalYAML() (interface{}, error)

func (r Rate) String() string

func (r Rate) Text(d Duration) string

func (r *Rate) UnmarshalJSON(b []byte) error

func (r *Rate) UnmarshalText(b []byte) error

func (r *Rate) UnmarshalYAML(y *yaml.Node) error

type Ratio ¶

type Ratio float64

Ratio represents percentage-like values.

The type supports parsing and formatting values like:

0.1
25%
0.5 %
...

Ratio values are stored as floating pointer numbers between 0 and 1 (assuming they stay within the 0-100% bounds), and formatted as percentages.

func ParseRatio(s string) (Ratio, error)

func (r Ratio) MarshalJSON() ([]byte, error)

func (r Ratio) MarshalText() ([]byte, error)

func (r Ratio) MarshalYAML() (interface{}, error)

func (r Ratio) String() string

func (r Ratio) Text(precision int) string

func (r *Ratio) UnmarshalJSON(b []byte) error

func (r *Ratio) UnmarshalText(b []byte) error

func (r *Ratio) UnmarshalYAML(y *yaml.Node) error

type Time ¶

type Time time.Time

Time represents absolute point in times. The implementation is based on time.Time.

The type supports all default time formats provided by the standard time package, as well as parsing and formatting values relative to a given time point, for example:

5 minutes ago
1h later
...

func ParseTime(s string) (Time, error)

func ParseTimeAt(s string, now time.Time) (Time, error)

func (t Time) IsZero() bool

func (t Time) MarshalJSON() ([]byte, error)

func (t Time) MarshalText() ([]byte, error)

func (t Time) MarshalYAML() (interface{}, error)

func (t Time) String() string

func (t Time) Text(now time.Time) string

func (t *Time) UnmarshalJSON(b []byte) error

func (t *Time) UnmarshalText(b []byte) error

func (t *Time) UnmarshalYAML(y *yaml.Node) error