README.md
1# datasize [](https://travis-ci.org/c2h5oh/datasize)
2
3Golang helpers for data sizes
4
5
6### Constants
7Just like `time` package provides `time.Second`, `time.Day` constants `datasize` provides:
8* `datasize.B` 1 byte
9* `datasize.KB` 1 kilobyte
10* `datasize.MB` 1 megabyte
11* `datasize.GB` 1 gigabyte
12* `datasize.TB` 1 terabyte
13* `datasize.PB` 1 petabyte
14* `datasize.EB` 1 exabyte
15
16### Helpers
17Just like `time` package provides `duration.Nanoseconds() uint64 `, `duration.Hours() float64` helpers `datasize` has
18* `ByteSize.Bytes() uint64`
19* `ByteSize.Kilobytes() float4`
20* `ByteSize.Megabytes() float64`
21* `ByteSize.Gigabytes() float64`
22* `ByteSize.Terabytes() float64`
23* `ByteSize.Petebytes() float64`
24* `ByteSize.Exabytes() float64`
25
26Warning: see limitations at the end of this document about a possible precission loss
27
28### Parsing strings
29`datasize.ByteSize` implements `TextUnmarshaler` interface and will automatically parse human readable strings into correct values where it is used:
30* `"10 MB"` -> `10* datasize.MB`
31* `"10240 g"` -> `10 * datasize.TB`
32* `"2000"` -> `2000 * datasize.B`
33* `"1tB"` -> `datasize.TB`
34* `"5 peta"` -> `5 * datasize.PB`
35* `"28 kilobytes"` -> `28 * datasize.KB`
36* `"1 gigabyte"` -> `1 * datasize.GB`
37
38You can also do it manually:
39```go
40var v datasize.ByteSize
41err := v.UnmarshalText([]byte("100 mb"))
42```
43
44### Printing
45`Bytesize.String()` uses largest unit allowing an integer value:
46 * `(102400 * datasize.MB).String()` -> `"100GB"`
47 * `(datasize.MB + datasize.KB).String()` -> `"1025KB"`
48
49Use `%d` format string to get value in bytes without a unit
50
51### JSON and other encoding
52Both `TextMarshaler` and `TextUnmarshaler` interfaces are implemented - JSON will just work. Other encoders will work provided they use those interfaces.
53
54### Human readable
55`ByteSize.HumanReadable()` or `ByteSize.HR()` returns a string with 1-3 digits, followed by 1 decimal place, a space and unit big enough to get 1-3 digits
56
57 * `(102400 * datasize.MB).String()` -> `"100.0 GB"`
58 * `(datasize.MB + 512 * datasize.KB).String()` -> `"1.5 MB"`
59
60### Limitations
61* The underlying data type for `data.ByteSize` is `uint64`, so values outside of 0 to 2^64-1 range will overflow
62* size helper functions (like `ByteSize.Kilobytes()`) return `float64`, which can't represent all possible values of `uint64` accurately:
63 * if the returned value is supposed to have no fraction (ie `(10 * datasize.MB).Kilobytes()`) accuracy loss happens when value is more than 2^53 larger than unit: `.Kilobytes()` over 8 petabytes, `.Megabytes()` over 8 exabytes
64 * if the returned value is supposed to have a fraction (ie `(datasize.PB + datasize.B).Megabytes()`) in addition to the above note accuracy loss may occur in fractional part too - larger integer part leaves fewer bytes to store fractional part, the smaller the remainder vs unit the move bytes are required to store the fractional part
65* Parsing a string with `Mb`, `Tb`, etc units will return a syntax error, because capital followed by lower case is commonly used for bits, not bytes
66* Parsing a string with value exceeding 2^64-1 bytes will return 2^64-1 and an out of range error
67
){kind=link}