File Size v1.0.0 FileSize View Source

A file size calculator, parser and formatter.

Usage

You can build your own file size by creating it with a number and a unit using the new/2 function. See the "Supported Units" section for a list of possible unit atoms.

iex> FileSize.new(16, :gb)
#FileSize<"16.0 GB">

Sigil

There is also a sigil defined that you can use to quickly build file sizes from a number and unit symbol. Just import the FileSize.Sigil module and you are ready to go. See the "Supported Units" section for a list of possible unit symbols.

iex> import FileSize.Sigil
...>
...> ~F(16 GB)
#FileSize<"16.0 GB">

From File

With from_file/1 it is also possible to retrieve the size of an actual file.

iex> FileSize.from_file("path/to/my/file.txt")
{:ok, #FileSize<"127.3 kB">}

Conversions

You can convert file sizes between different units:

convert/2 - Convert file size from one unit to another.
change_unit_system/2 - Convert file size from one unit system to another (SI to IEC unit and vice-versa).

Calculations

You can calculate with file sizes. The particular units don't need to be the same for that.

add/2 - Add two file sizes.
subtract/2 - Subtracts two file sizes.

Comparison

For comparison the particular units don't need to be the same.

compare/2 - Compares two file sizes and returns a value indicating whether one file size is greater than or less than the other.
equals?/2 - Determines whether two file sizes are equal.

Supported Units

Bit-based

SI (Système international d'unités)

Atom	Symbol	Name	Factor
`:bit`	bit	Bits	1
`:kbit`	kbit	Kilobits	1000
`:mbit`	Mbit	Megabits	1000^2
`:gbit`	GBit	Gigabits	1000^3
`:tbit`	TBit	Terabits	1000^4
`:pbit`	PBit	Petabits	1000^5
`:ebit`	EBit	Exabits	1000^6
`:zbit`	ZBit	Zetabits	1000^7
`:ybit`	YBit	Yottabits	1000^8

IEC (International Electrotechnical Commission)

Atom	Symbol	Name	Factor
`:bit`	Bit	Bits	1
`:kibit`	Kibit	Kibibits	1024
`:mibit`	Mibit	Mebibits	1024^2
`:gibit`	Gibit	Gibibits	1024^3
`:tibit`	Tibit	Tebibits	1024^4
`:pibit`	Pibit	Pebibits	1024^5
`:eibit`	Eibit	Exbibits	1024^6
`:zibit`	Zibit	Zebibits	1024^7
`:yibit`	Yibit	Yobibits	1024^8

Byte-based

The most common unit of digital information. A single Byte represents 8 Bits.

SI (Système international d'unités)

Atom	Symbol	Name	Factor
`:b`	B	Bytes	1
`:kb`	kB	Kilobytes	1000
`:mb`	MB	Megabytes	1000^2
`:gb`	GB	Gigabytes	1000^3
`:tb`	TB	Terabytes	1000^4
`:pb`	PB	Petabytes	1000^5
`:eb`	EB	Exabytes	1000^6
`:zb`	ZB	Zetabytes	1000^7
`:yb`	YB	Yottabytes	1000^8

IEC (International Electrotechnical Commission)

Atom	Symbol	Name	Factor
`:b`	B	Bytes	1
`:kib`	KiB	Kibibytes	1024
`:mib`	MiB	Mebibytes	1024^2
`:gib`	GiB	Gibibytes	1024^3
`:tib`	TiB	Tebibytes	1024^4
`:pib`	PiB	Pebibytes	1024^5
`:eib`	EiB	Exbibytes	1024^6
`:zib`	ZiB	Zebibytes	1024^7
`:yib`	YiB	Yobibytes	1024^8

Link to this section Summary

Types

iec_unit()

A type that defines the IEC bit and byte units.

si_unit()

A type that defines the SI bit and byte units.

t()

A type that is a union of the bit and byte types.

unit()

A type that is a union of the bit and byte unit types.

unit_symbol()

A type that represents a unit symbol.

unit_system()

A type that contains the available unit systems.

Functions

__config__()

Gets the configuration.

add(size, other_size)

See FileSize.Calculable.add/2.

add(size, other_size, as_unit)

Adds two file sizes like add/2 and converts the result to the specified unit.

change_unit_system(size, unit_system)

Uses the unit from the given size to determine the equivalent unit in the given unit system. The size is then converted to this unit.

compare(size, other_size)

See FileSize.Comparable.compare/2.

convert(size, to_unit)

See FileSize.Convertible.convert/2.

equals?(size, other_size)

Determines whether two file sizes are equal.

format(size, opts \\ [])

See FileSize.Formatter.format/2.

from_bits(bits, as_unit)

Builds a new file size from the given number of bits and converts it to the specified unit.

from_bytes(bytes, as_unit)

Builds a new file size from the given number of bytes and converts it to the specified unit.

from_file(path, as_unit \\ :b)

Determines the size of the file at the given path.

from_file!(path, as_unit \\ :b)

Determines the size of the file at the given path. Raises when the file could not be found.

new(value, unit \\ :b)

Builds a new file size. Raises when the given unit could not be found.

parse(value)

See FileSize.Parser.parse/1.

parse!(value)

See FileSize.Parser.parse!/1.

subtract(size, other_size)

See FileSize.Calculable.subtract/2.

subtract(size, other_size, as_unit)

Subtracts two file sizes like subtract/2 and converts the result to the specified unit.

Link to this section Types

iec_unit()

iec_unit() :: FileSize.Bit.iec_unit() | FileSize.Byte.iec_unit()

A type that defines the IEC bit and byte units.

si_unit()

si_unit() :: FileSize.Bit.si_unit() | FileSize.Byte.si_unit()

A type that defines the SI bit and byte units.

t()

t() :: FileSize.Bit.t() | FileSize.Byte.t()

A type that is a union of the bit and byte types.

unit()

unit() :: iec_unit() | si_unit()

A type that is a union of the bit and byte unit types.

unit_symbol()

unit_symbol() :: String.t()

A type that represents a unit symbol.

unit_system()

unit_system() :: :iec | :si

A type that contains the available unit systems.

Link to this section Functions

__config__()

__config__() :: Keyword.t()

Gets the configuration.

add(size, other_size) View Source

See FileSize.Calculable.add/2.

add(size, other_size, as_unit)

add(t(), t(), unit()) :: t()

Adds two file sizes like add/2 and converts the result to the specified unit.

Example

iex> FileSize.add(FileSize.new(1, :kb), FileSize.new(2, :kb), :b)
#FileSize<"3000 B">

change_unit_system(size, unit_system)

change_unit_system(t(), unit_system()) :: t()

Uses the unit from the given size to determine the equivalent unit in the given unit system. The size is then converted to this unit.

Examples

iex> FileSize.change_unit_system(FileSize.new(2, :kb), :iec)
#FileSize<"1.953125 KiB">

iex> FileSize.change_unit_system(FileSize.new(2, :kib), :si)
#FileSize<"2.048 kB">

iex> FileSize.change_unit_system(FileSize.new(2, :b), :unknown)
** (FileSize.InvalidUnitSystemError) Invalid unit system: :unknown

compare(size, other_size) View Source

See FileSize.Comparable.compare/2.

convert(size, to_unit) View Source

See FileSize.Convertible.convert/2.

equals?(size, other_size)

equals?(t(), t()) :: boolean()

Determines whether two file sizes are equal.

Examples

iex> FileSize.equals?(FileSize.new(2, :b), FileSize.new(16, :bit))
true

iex> FileSize.equals?(FileSize.new(2, :b), FileSize.new(2, :b))
true

iex> FileSize.equals?(FileSize.new(1, :b), FileSize.new(2, :b))
false

format(size, opts \\ []) View Source

See FileSize.Formatter.format/2.

from_bits(bits, as_unit)

from_bits(integer(), unit()) :: t()

Builds a new file size from the given number of bits and converts it to the specified unit.

Examples

iex> FileSize.from_bits(16, :b)
#FileSize<"2 B">

iex> FileSize.from_bits(16, :unknown)
** (FileSize.InvalidUnitError) Invalid unit: :unknown

from_bytes(bytes, as_unit)

from_bytes(integer(), unit()) :: t()

Builds a new file size from the given number of bytes and converts it to the specified unit.

Examples

iex> FileSize.from_bytes(2000, :kb)
#FileSize<"2.0 kB">

iex> FileSize.from_bytes(2000, :kbit)
#FileSize<"16.0 kbit">

iex> FileSize.from_bytes(2000, :unknown)
** (FileSize.InvalidUnitError) Invalid unit: :unknown

from_file(path, as_unit \\ :b)

from_file(Path.t(), unit()) :: {:ok, t()} | {:error, File.posix()}

Determines the size of the file at the given path.

Examples

iex> FileSize.from_file("path/to/my/file.txt")
{:ok, #FileSize<"133.7 kB">}

iex> FileSize.from_file("not/existing/file.txt")
{:error, :enoent}

from_file!(path, as_unit \\ :b)

from_file!(Path.t(), unit()) :: t() | no_return()

Determines the size of the file at the given path. Raises when the file could not be found.

Examples

iex> FileSize.from_file!("path/to/my/file.txt")
#FileSize<"133.7 kB">

iex> FileSize.from_file!("not/existing/file.txt")
** (File.Error) could not read file stats "not/existing/file.txt": no such file or directory

new(value, unit \\ :b)

new(number(), unit()) :: t() | no_return()

Builds a new file size. Raises when the given unit could not be found.

Examples

iex> FileSize.new(2.5, :mb)
#FileSize<"2.5 MB">

iex> FileSize.new(214, :kib)
#FileSize<"214.0 KiB">

iex> FileSize.new(3, :bit)
#FileSize<"3 bit">

parse(value) View Source

See FileSize.Parser.parse/1.

parse!(value) View Source

See FileSize.Parser.parse!/1.

subtract(size, other_size) View Source

See FileSize.Calculable.subtract/2.

subtract(size, other_size, as_unit)

subtract(t(), t(), unit()) :: t()

Subtracts two file sizes like subtract/2 and converts the result to the specified unit.

Example

iex> FileSize.subtract(FileSize.new(2, :b), FileSize.new(6, :bit), :bit)
#FileSize<"10 bit">

v3.0.1 v3.0.0 v2.1.1 v2.1.0 v2.0.0 v1.3.0 v1.2.0 v1.1.0 v1.0.1 v1.0.0

File Size v1.0.0 FileSize View Source

Usage

Sigil

From File

Conversions

Calculations

Comparison

Supported Units

Bit-based

SI (Système international d'unités)

IEC (International Electrotechnical Commission)

Byte-based

SI (Système international d'unités)

IEC (International Electrotechnical Commission)

Link to this section Summary

Types

Functions

Link to this section Types

iec_unit() View Source iec_unit() :: FileSize.Bit.iec_unit() | FileSize.Byte.iec_unit()

si_unit() View Source si_unit() :: FileSize.Bit.si_unit() | FileSize.Byte.si_unit()

t() View Source t() :: FileSize.Bit.t() | FileSize.Byte.t()

unit() View Source unit() :: iec_unit() | si_unit()

unit_symbol() View Source unit_symbol() :: String.t()

unit_system() View Source unit_system() :: :iec | :si

Link to this section Functions

__config__() View Source __config__() :: Keyword.t()

add(size, other_size) View Source

add(size, other_size, as_unit) View Source add(t(), t(), unit()) :: t()

Example

change_unit_system(size, unit_system) View Source change_unit_system(t(), unit_system()) :: t()

Examples

compare(size, other_size) View Source

convert(size, to_unit) View Source

equals?(size, other_size) View Source equals?(t(), t()) :: boolean()

Examples

format(size, opts \\ []) View Source

from_bits(bits, as_unit) View Source from_bits(integer(), unit()) :: t()

Examples

from_bytes(bytes, as_unit) View Source from_bytes(integer(), unit()) :: t()

Examples

from_file(path, as_unit \\ :b) View Source from_file(Path.t(), unit()) :: {:ok, t()} | {:error, File.posix()}

Examples

from_file!(path, as_unit \\ :b) View Source from_file!(Path.t(), unit()) :: t() | no_return()

Examples

new(value, unit \\ :b) View Source new(number(), unit()) :: t() | no_return()

Examples

parse(value) View Source

parse!(value) View Source

subtract(size, other_size) View Source

subtract(size, other_size, as_unit) View Source subtract(t(), t(), unit()) :: t()

Example

iec_unit() View Source

iec_unit() :: FileSize.Bit.iec_unit() | FileSize.Byte.iec_unit()

si_unit() View Source

si_unit() :: FileSize.Bit.si_unit() | FileSize.Byte.si_unit()

t() View Source

t() :: FileSize.Bit.t() | FileSize.Byte.t()

unit() View Source

unit() :: iec_unit() | si_unit()

unit_symbol() View Source

unit_symbol() :: String.t()

unit_system() View Source

unit_system() :: :iec | :si

config() View Source

config() :: Keyword.t()

add(size, other_size, as_unit) View Source

add(t(), t(), unit()) :: t()

change_unit_system(size, unit_system) View Source

change_unit_system(t(), unit_system()) :: t()

equals?(size, other_size) View Source

equals?(t(), t()) :: boolean()

from_bits(bits, as_unit) View Source

from_bits(integer(), unit()) :: t()

from_bytes(bytes, as_unit) View Source

from_bytes(integer(), unit()) :: t()

from_file(path, as_unit \\ :b) View Source

from_file(Path.t(), unit()) :: {:ok, t()} | {:error, File.posix()}

from_file!(path, as_unit \\ :b) View Source

from_file!(Path.t(), unit()) :: t() | no_return()

new(value, unit \\ :b) View Source

new(number(), unit()) :: t() | no_return()

subtract(size, other_size, as_unit) View Source

subtract(t(), t(), unit()) :: t()