units

README

Introduction

go-units is a library to transform human friendly measurements into machine friendly values.

Usage

See the docs in godoc for examples and documentation.

Copyright and license

Copyright © 2015 Docker, Inc.

go-units is licensed under the Apache License, Version 2.0. See LICENSE for the full text of the license.

Documentation

Overview

Package units provides helper function to parse and print size and time units in human-readable format.

Index

• Constants
• func BytesSize(size float64) string
• func CustomSize(format string, size float64, base float64, _map []string) string
• func FromHumanSize(size string) (int64, error)
• func HumanDuration(d time.Duration) string
• func HumanSize(size float64) string
• func HumanSizeWithPrecision(size float64, precision int) string
• func RAMInBytes(size string) (int64, error)
• type Rlimit
• type Ulimit
  • func ParseUlimit(val string) (*Ulimit, error)
  • func (u *Ulimit) GetRlimit() (*Rlimit, error)
  • func (u *Ulimit) String() string

Examples

• BytesSize
• FromHumanSize
• HumanDuration
• HumanSize
• ParseUlimit
• RAMInBytes

Constants

const (
	KB = 1000
	MB = 1000 * KB
	GB = 1000 * MB
	TB = 1000 * GB
	PB = 1000 * TB

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

See: http://en.wikipedia.org/wiki/Binary_prefix

Functions

func BytesSize

func BytesSize(size float64) string

BytesSize returns a human-readable size in bytes, kibibytes, mebibytes, gibibytes, or tebibytes (eg. "44kiB", "17MiB").

Example

fmt.Println(BytesSize(1024))
fmt.Println(BytesSize(1024 * 1024))
fmt.Println(BytesSize(1048576))
fmt.Println(BytesSize(2 * MiB))
fmt.Println(BytesSize(3.42 * GiB))
fmt.Println(BytesSize(5.372 * TiB))
fmt.Println(BytesSize(2.22 * PiB))

func CustomSize

func CustomSize(format string, size float64, base float64, _map []string) string

CustomSize returns a human-readable approximation of a size using custom format.

func FromHumanSize

func FromHumanSize(size string) (int64, error)

FromHumanSize returns an integer from a human-readable specification of a size using SI standard (eg. "44kB", "17MB").

Example

fmt.Println(FromHumanSize("32"))
fmt.Println(FromHumanSize("32b"))
fmt.Println(FromHumanSize("32B"))
fmt.Println(FromHumanSize("32k"))
fmt.Println(FromHumanSize("32K"))
fmt.Println(FromHumanSize("32kb"))
fmt.Println(FromHumanSize("32Kb"))
fmt.Println(FromHumanSize("32Mb"))
fmt.Println(FromHumanSize("32Gb"))
fmt.Println(FromHumanSize("32Tb"))
fmt.Println(FromHumanSize("32Pb"))

func HumanDuration

func HumanDuration(d time.Duration) string

HumanDuration returns a human-readable approximation of a duration (eg. "About a minute", "4 hours ago", etc.).

Example

fmt.Println(HumanDuration(450 * time.Millisecond))
fmt.Println(HumanDuration(47 * time.Second))
fmt.Println(HumanDuration(1 * time.Minute))
fmt.Println(HumanDuration(3 * time.Minute))
fmt.Println(HumanDuration(35 * time.Minute))
fmt.Println(HumanDuration(35*time.Minute + 40*time.Second))
fmt.Println(HumanDuration(1 * time.Hour))
fmt.Println(HumanDuration(1*time.Hour + 45*time.Minute))
fmt.Println(HumanDuration(3 * time.Hour))
fmt.Println(HumanDuration(3*time.Hour + 59*time.Minute))
fmt.Println(HumanDuration(3*time.Hour + 60*time.Minute))
fmt.Println(HumanDuration(24 * time.Hour))
fmt.Println(HumanDuration(24*time.Hour + 12*time.Hour))
fmt.Println(HumanDuration(2 * 24 * time.Hour))
fmt.Println(HumanDuration(7 * 24 * time.Hour))
fmt.Println(HumanDuration(13*24*time.Hour + 5*time.Hour))
fmt.Println(HumanDuration(2 * 7 * 24 * time.Hour))
fmt.Println(HumanDuration(2*7*24*time.Hour + 4*24*time.Hour))
fmt.Println(HumanDuration(3 * 7 * 24 * time.Hour))
fmt.Println(HumanDuration(4 * 7 * 24 * time.Hour))
fmt.Println(HumanDuration(4*7*24*time.Hour + 3*24*time.Hour))
fmt.Println(HumanDuration(1 * 30 * 24 * time.Hour))
fmt.Println(HumanDuration(1*30*24*time.Hour + 2*7*24*time.Hour))
fmt.Println(HumanDuration(2 * 30 * 24 * time.Hour))
fmt.Println(HumanDuration(3*30*24*time.Hour + 1*7*24*time.Hour))
fmt.Println(HumanDuration(5*30*24*time.Hour + 2*7*24*time.Hour))
fmt.Println(HumanDuration(13 * 30 * 24 * time.Hour))
fmt.Println(HumanDuration(23 * 30 * 24 * time.Hour))
fmt.Println(HumanDuration(24 * 30 * 24 * time.Hour))
fmt.Println(HumanDuration(24*30*24*time.Hour + 2*7*24*time.Hour))
fmt.Println(HumanDuration(3*365*24*time.Hour + 2*30*24*time.Hour))

func HumanSize

func HumanSize(size float64) string

HumanSize returns a human-readable approximation of a size capped at 4 valid numbers (eg. "2.746 MB", "796 KB").

Example

fmt.Println(HumanSize(1000))
fmt.Println(HumanSize(1024))
fmt.Println(HumanSize(1000000))
fmt.Println(HumanSize(1048576))
fmt.Println(HumanSize(2 * MB))
fmt.Println(HumanSize(float64(3.42 * GB)))
fmt.Println(HumanSize(float64(5.372 * TB)))
fmt.Println(HumanSize(float64(2.22 * PB)))

func HumanSizeWithPrecision

func HumanSizeWithPrecision(size float64, precision int) string

HumanSizeWithPrecision allows the size to be in any precision, instead of 4 digit precision used in units.HumanSize.

func RAMInBytes

func RAMInBytes(size string) (int64, error)

RAMInBytes parses a human-readable string representing an amount of RAM in bytes, kibibytes, mebibytes, gibibytes, or tebibytes and returns the number of bytes, or -1 if the string is unparseable. Units are case-insensitive, and the 'b' suffix is optional.

Example

fmt.Println(RAMInBytes("32"))
fmt.Println(RAMInBytes("32b"))
fmt.Println(RAMInBytes("32B"))
fmt.Println(RAMInBytes("32k"))
fmt.Println(RAMInBytes("32K"))
fmt.Println(RAMInBytes("32kb"))
fmt.Println(RAMInBytes("32Kb"))
fmt.Println(RAMInBytes("32Mb"))
fmt.Println(RAMInBytes("32Gb"))
fmt.Println(RAMInBytes("32Tb"))
fmt.Println(RAMInBytes("32Pb"))
fmt.Println(RAMInBytes("32PB"))
fmt.Println(RAMInBytes("32P"))

Types

type Rlimit

type Rlimit struct {
	Type int    `json:"type,omitempty"`
	Hard uint64 `json:"hard,omitempty"`
	Soft uint64 `json:"soft,omitempty"`
}

Rlimit specifies the resource limits, such as max open files.

type Ulimit

type Ulimit struct {
	Name string
	Hard int64
	Soft int64
}

Ulimit is a human friendly version of Rlimit.

func ParseUlimit

func ParseUlimit(val string) (*Ulimit, error)

ParseUlimit parses and returns a Ulimit from the specified string.

Example

fmt.Println(ParseUlimit("nofile=512:1024"))
fmt.Println(ParseUlimit("nofile=1024"))
fmt.Println(ParseUlimit("cpu=2:4"))
fmt.Println(ParseUlimit("cpu=6"))

func (*Ulimit) GetRlimit

func (u *Ulimit) GetRlimit() (*Rlimit, error)

GetRlimit returns the RLimit corresponding to Ulimit.

func (*Ulimit) String

func (u *Ulimit) String() string