ByteCount (ByteCount v1.0.0)

Human-friendly byte sizes – construct, parse, format, and do math.

Examples

iex> ByteCount.gib(523) |> to_string()
"523.0 GiB"

iex> ByteCount.kib(42) |> ByteCount.format(style: :si, short: true)
"43.0k"

Summary

Types

format_opts()

t()

Functions

add(byte_count, byte_count_or_integer)

Add two ByteCount structs or byte count to an existing struct.

b(bytes)

Alias for new/1. Creates a %ByteCount{} from raw bytes.

divide(byte_count, byte_count_or_integer)

Divide two ByteCount structs or byte count to an existing struct.

eb(n)

Creates a %ByteCount{} from exabytes (1 EB = 10¹⁸ bytes).

eib(n)

Creates a %ByteCount{} from exbibytes (1 EiB = 2⁶⁰ bytes).

format(struct)

Return a human-readable string using the IEC style and default options.

format(struct, opts)

Return a human-readable string representing of the byte count customizable using the following options

gb(n)

Creates a %ByteCount{} from gigabytes (1 GB = 10⁹ bytes).

gib(n)

Creates a %ByteCount{} from gibibytes (1 GiB = 2³⁰ bytes).

kb(n)

Creates a %ByteCount{} from kilobytes (1 KB = 10³ bytes).

kib(n)

Creates a %ByteCount{} from kibibytes (1 KiB = 2¹⁰ bytes).

mb(n)

Creates a %ByteCount{} from megabytes (1 MB = 10⁶ bytes).

mib(n)

Creates a %ByteCount{} from mebibytes (1 MiB = 2²⁰ bytes).

multiply(byte_count, byte_count_or_integer)

Multiply two ByteCount structs or byte count to an existing struct.

new(bytes)

Construct a new struct from given byte count integer.

parse(string)

Parse byte count given as string.

parse!(string)

Parse byte count or raise on error.

pb(n)

Creates a %ByteCount{} from petabytes (1 PB = 10¹⁵ bytes).

pib(n)

Creates a %ByteCount{} from pebibytes (1 PiB = 2⁵⁰ bytes).

qb(n)

Creates a %ByteCount{} from quettabytes (1 QB = 10³⁰ bytes).

qib(n)

Creates a %ByteCount{} from quebibytes (1 QiB = 2¹⁰⁰ bytes).

rb(n)

Creates a %ByteCount{} from ronnabytes (1 RB = 10²⁷ bytes).

rib(n)

Creates a %ByteCount{} from robibytes (1 RiB = 2⁹⁰ bytes).

subtract(byte_count, byte_count_or_integer)

Subtract two ByteCount structs or byte count to an existing struct.

tb(n)

Creates a %ByteCount{} from terabytes (1 TB = 10¹² bytes).

tib(n)

Creates a %ByteCount{} from tebibytes (1 TiB = 2⁴⁰ bytes).

to_integer(struct)

Return byte count as an integer

yb(n)

Creates a %ByteCount{} from yottabytes (1 YB = 10²⁴ bytes).

yib(n)

Creates a %ByteCount{} from yobibytes (1 YiB = 2⁸⁰ bytes).

zb(n)

Creates a %ByteCount{} from zettabytes (1 ZB = 10²¹ bytes).

zib(n)

Creates a %ByteCount{} from zebibytes (1 ZiB = 2⁷⁰ bytes).

Types

format_opts()

@type format_opts() :: [
  style: :iec | :si,
  short: boolean(),
  precision: non_neg_integer()
]

t()

@type t() :: %ByteCount{bytes: non_neg_integer()}

Functions

add(byte_count, byte_count_or_integer)

@spec add(t(), t() | integer()) :: t()

Add two ByteCount structs or byte count to an existing struct.

Examples

iex> ByteCount.add(ByteCount.kb(1), ByteCount.b(23))
%ByteCount{bytes: 1023}

iex> ByteCount.add(ByteCount.kb(1), 1)
%ByteCount{bytes: 1001}

b(bytes)

@spec b(non_neg_integer()) :: t()

Alias for new/1. Creates a %ByteCount{} from raw bytes.

Examples

iex> ByteCount.b(512)
%ByteCount{bytes: 512}

divide(byte_count, byte_count_or_integer)

@spec divide(t(), t() | integer()) :: t()

Divide two ByteCount structs or byte count to an existing struct.

Examples

iex> ByteCount.divide(ByteCount.kb(1), ByteCount.kb(1))
%ByteCount{bytes: 1}

iex> ByteCount.divide(ByteCount.kb(1), 1000)
%ByteCount{bytes: 1}

eb(n)

@spec eb(non_neg_integer()) :: t()

Creates a %ByteCount{} from exabytes (1 EB = 10¹⁸ bytes).

eib(n)

@spec eib(non_neg_integer()) :: t()

Creates a %ByteCount{} from exbibytes (1 EiB = 2⁶⁰ bytes).

format(struct)

@spec format(t()) :: String.t()

Return a human-readable string using the IEC style and default options.

To customize formating see format/2.

format(struct, opts)

@spec format(t(), format_opts()) :: String.t()

Return a human-readable string representing of the byte count customizable using the following options:

Options:

style: :iec | :si (default is :iec)
short: true | false (default is false) → "43.0k" instead of "43.0 KiB"
precision: 1 | 2 | ... (default is 1)

Examples

iex> ByteCount.kib(4) |> ByteCount.format()
"4.0 KiB"

iex> ByteCount.kb(4) |> ByteCount.format(style: :si, short: true, precision: 0)
"4k"

gb(n)

@spec gb(non_neg_integer()) :: t()

Creates a %ByteCount{} from gigabytes (1 GB = 10⁹ bytes).

gib(n)

@spec gib(non_neg_integer()) :: t()

Creates a %ByteCount{} from gibibytes (1 GiB = 2³⁰ bytes).

kb(n)

@spec kb(non_neg_integer()) :: t()

Creates a %ByteCount{} from kilobytes (1 KB = 10³ bytes).

kib(n)

@spec kib(non_neg_integer()) :: t()

Creates a %ByteCount{} from kibibytes (1 KiB = 2¹⁰ bytes).

mb(n)

@spec mb(non_neg_integer()) :: t()

Creates a %ByteCount{} from megabytes (1 MB = 10⁶ bytes).

mib(n)

@spec mib(non_neg_integer()) :: t()

Creates a %ByteCount{} from mebibytes (1 MiB = 2²⁰ bytes).

multiply(byte_count, byte_count_or_integer)

@spec multiply(t(), t() | integer()) :: t()

Multiply two ByteCount structs or byte count to an existing struct.

Examples

iex> ByteCount.multiply(ByteCount.kb(1), ByteCount.b(2))
%ByteCount{bytes: 2000}

iex> ByteCount.multiply(ByteCount.kb(1), 2)
%ByteCount{bytes: 2000}

new(bytes)

@spec new(non_neg_integer()) :: t()

Construct a new struct from given byte count integer.

Examples

iex> ByteCount.new(1024)
%ByteCount{bytes: 1024}

parse(string)

@spec parse(String.t()) :: {:ok, t()} | {:error, any()}

Parse byte count given as string.

Examples

iex> ByteCount.parse("10")
{:ok, %ByteCount{bytes: 10}}

iex> ByteCount.parse("10 kb")
{:ok, %ByteCount{bytes: 10000}}

iex> ByteCount.parse("10k")
{:ok, %ByteCount{bytes: 10000}}

parse!(string)

@spec parse!(String.t()) :: t() | no_return()

Parse byte count or raise on error.

Examples

iex> ByteCount.parse!("10")
%ByteCount{bytes: 10}

pb(n)

@spec pb(non_neg_integer()) :: t()

Creates a %ByteCount{} from petabytes (1 PB = 10¹⁵ bytes).

pib(n)

@spec pib(non_neg_integer()) :: t()

Creates a %ByteCount{} from pebibytes (1 PiB = 2⁵⁰ bytes).

qb(n)

@spec qb(non_neg_integer()) :: t()

Creates a %ByteCount{} from quettabytes (1 QB = 10³⁰ bytes).

qib(n)

@spec qib(non_neg_integer()) :: t()

Creates a %ByteCount{} from quebibytes (1 QiB = 2¹⁰⁰ bytes).

rb(n)

@spec rb(non_neg_integer()) :: t()

Creates a %ByteCount{} from ronnabytes (1 RB = 10²⁷ bytes).

rib(n)

@spec rib(non_neg_integer()) :: t()

Creates a %ByteCount{} from robibytes (1 RiB = 2⁹⁰ bytes).

subtract(byte_count, byte_count_or_integer)

@spec subtract(t(), t() | integer()) :: t()

Subtract two ByteCount structs or byte count to an existing struct.

Examples

iex> ByteCount.subtract(ByteCount.kb(3), ByteCount.kb(3))
%ByteCount{bytes: 0}

iex> ByteCount.subtract(ByteCount.kb(3), 3000)
%ByteCount{bytes: 0}

tb(n)

@spec tb(non_neg_integer()) :: t()

Creates a %ByteCount{} from terabytes (1 TB = 10¹² bytes).

tib(n)

@spec tib(non_neg_integer()) :: t()

Creates a %ByteCount{} from tebibytes (1 TiB = 2⁴⁰ bytes).

to_integer(struct)

@spec to_integer(t()) :: integer()

Return byte count as an integer

Examples

iex> ByteCount.kb(1) |> ByteCount.to_integer()
1000

yb(n)

@spec yb(non_neg_integer()) :: t()

Creates a %ByteCount{} from yottabytes (1 YB = 10²⁴ bytes).

yib(n)

@spec yib(non_neg_integer()) :: t()

Creates a %ByteCount{} from yobibytes (1 YiB = 2⁸⁰ bytes).

zb(n)

@spec zb(non_neg_integer()) :: t()

Creates a %ByteCount{} from zettabytes (1 ZB = 10²¹ bytes).

zib(n)

@spec zib(non_neg_integer()) :: t()

Creates a %ByteCount{} from zebibytes (1 ZiB = 2⁷⁰ bytes).