File Size v1.3.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 use the FileSize module and you are ready to go. See the "Supported Units" section for a list of possible unit symbols.

iex> use FileSize
...>
...> ~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 or unit systems by using the convert/2 function.

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 units of the particular file sizes 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.
lt?/2 - Determines whether file size a < b.
lteq?/2 - Determines whether file size a <= b.
gt?/2 - Determines whether file size a > b.
gteq?/2 - Determines whether file size a >= b.

To sort a collection of file sizes from smallest to greatest, you can use lteq?/2 as sort function. To sort descending use gteq?/2.

iex> sizes = [~F(16 GB), ~F(100 Mbit), ~F(27.4 MB), ~F(16 Gbit)]
...> Enum.sort(sizes, &FileSize.lteq?/2)
[#FileSize<"100.0 Mbit">, #FileSize<"27.4 MB">, #FileSize<"16.0 Gbit">, #FileSize<"16.0 GB">]

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_or_unit_system)

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

change_unit_system(size, unit_system) deprecated

Converts the given file size to a given unit system.

compare(size, other_size)

See FileSize.Comparable.compare/2.

convert(size, to_unit_or_unit_system)

Converts the given file size to a given unit or unit system.

equals?(size, other_size)

Determines whether two file sizes are equal.

format(size, opts \\ [])

See FileSize.Formatter.format/2.

from_bits(bytes, as_unit_or_unit_system \\ {:system, :si})

Builds a new file size from the given number of bits.

from_bytes(bytes, as_unit_or_unit_system \\ {:system, :si})

Builds a new file size from the given number of bytes.

from_file(path, as_unit_or_unit_system \\ :b)

Determines the size of the file at the given path.

from_file!(path, as_unit_or_unit_system \\ :b)

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

gt?(size, other_size)

Determines whether the first file size is greater than the second one.

gteq?(size, other_size)

Determines whether the first file size is less or equal to than the second one.

lt?(size, other_size)

Determines whether the first file size is less than the second one.

lteq?(size, other_size)

Determines whether the first file size is less or equal to than the second one.

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.

scale(size, unit_system \\ nil)

Converts the given file size to the most appropriate unit.

subtract(size, other_size)

See FileSize.Calculable.subtract/2.

subtract(size, other_size, as_unit_or_unit_system)

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_or_unit_system)

add(t(), t(), unit() | {:system, unit_system()}) :: 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">

iex> FileSize.add(FileSize.new(1, :kb), FileSize.new(2, :kb), {:system, :iec})
#FileSize<"2.9296875 KiB">

change_unit_system(size, unit_system)

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

This function is deprecated. Use convert/2 instead.

Converts the given file size to a given unit system.

compare(size, other_size) View Source

See FileSize.Comparable.compare/2.

convert(size, to_unit_or_unit_system) View Source

Converts the given file size to a given unit or unit system.

Examples

iex> FileSize.convert(FileSize.new(2, :kb), :b)
#FileSize<"2000 B">

iex> FileSize.convert(FileSize.new(2000, :b), :kb)
#FileSize<"2.0 kB">

iex> FileSize.convert(FileSize.new(20, :kb), :kbit)
#FileSize<"160.0 kbit">

iex> FileSize.convert(FileSize.new(2, :kb), {:system, :iec})
#FileSize<"1.953125 KiB">

iex> FileSize.convert(FileSize.new(2, :kib), {:system, :si})
#FileSize<"2.048 kB">

iex> FileSize.convert(FileSize.new(2000, :b), :unknown)
** (FileSize.InvalidUnitError) Invalid unit: :unknown

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

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(bytes, as_unit_or_unit_system \\ {:system, :si})

from_bits(integer(), unit() | {:system, unit_system()}) :: t()

Builds a new file size from the given number of bits.

Example

iex> FileSize.from_bits(2000)
#FileSize<"2.0 kbit">

iex> FileSize.from_bits(2000, {:system, :iec})
#FileSize<"1.953125 Kibit">

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_or_unit_system \\ {:system, :si})

from_bytes(integer(), unit() | {:system, unit_system()}) :: t()

Builds a new file size from the given number of bytes.

Example

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

iex> FileSize.from_bytes(2000, {:system, :iec})
#FileSize<"1.953125 KiB">

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_or_unit_system \\ :b)

from_file(Path.t(), unit() | {:system, unit_system()}) ::
  {: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("path/to/my/file.txt", {:system, :iec})
{:ok, #FileSize<"133.7 KiB">}

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

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

from_file!(path, as_unit_or_unit_system \\ :b)

from_file!(Path.t(), unit() | {:system, unit_system()}) :: 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!("path/to/my/file.txt", {:system, :iec})
#FileSize<"133.7 KiB">

iex> FileSize.from_file!("path/to/my/file.txt", :mb)
#FileSize<"0.13 MB">

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

gt?(size, other_size) (since 1.2.0)

gt?(t(), t()) :: boolean()

Determines whether the first file size is greater than the second one.

Examples

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

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

gteq?(size, other_size) (since 1.2.0)

gteq?(t(), t()) :: boolean()

Determines whether the first file size is less or equal to than the second one.

Examples

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

iex> FileSize.gteq?(FileSize.new(1, :b), FileSize.new(1, :b))
true

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

lt?(size, other_size) (since 1.2.0)

lt?(t(), t()) :: boolean()

Determines whether the first file size is less than the second one.

Examples

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

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

lteq?(size, other_size) (since 1.2.0)

lteq?(t(), t()) :: boolean()

Determines whether the first file size is less or equal to than the second one.

Examples

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

iex> FileSize.lteq?(FileSize.new(1, :b), FileSize.new(1, :b))
true

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

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.

scale(size, unit_system \\ nil) (since 1.1.0)

scale(t(), nil | unit_system()) :: t()

Converts the given file size to the most appropriate unit.

Examples

iex> FileSize.scale(FileSize.new(2000, :b))
#FileSize<"2.0 kB">

iex> FileSize.scale(FileSize.new(2_000_000, :kb))
#FileSize<"2.0 GB">

iex> FileSize.scale(FileSize.new(2_000_000, :kb), :iec)
#FileSize<"1.862645149230957 GiB">

subtract(size, other_size) View Source

See FileSize.Calculable.subtract/2.

subtract(size, other_size, as_unit_or_unit_system)

subtract(t(), t(), unit() | {:system, unit_system()}) :: 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">

iex> FileSize.subtract(FileSize.new(3, :kb), FileSize.new(1, :kb), {:system, :iec})
#FileSize<"1.953125 KiB">

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.3.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_or_unit_system) View Source add(t(), t(), unit() | {:system, unit_system()}) :: t()

Example

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

compare(size, other_size) View Source

convert(size, to_unit_or_unit_system) View Source

Examples

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

Examples

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

from_bits(bytes, as_unit_or_unit_system \\ {:system, :si}) View Source from_bits(integer(), unit() | {:system, unit_system()}) :: t()

Example

from_bytes(bytes, as_unit_or_unit_system \\ {:system, :si}) View Source from_bytes(integer(), unit() | {:system, unit_system()}) :: t()

Example

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

Examples

from_file!(path, as_unit_or_unit_system \\ :b) View Source from_file!(Path.t(), unit() | {:system, unit_system()}) :: t() | no_return()

Examples

gt?(size, other_size) View Source (since 1.2.0) gt?(t(), t()) :: boolean()

Examples

gteq?(size, other_size) View Source (since 1.2.0) gteq?(t(), t()) :: boolean()

Examples

lt?(size, other_size) View Source (since 1.2.0) lt?(t(), t()) :: boolean()

Examples

lteq?(size, other_size) View Source (since 1.2.0) lteq?(t(), t()) :: boolean()

Examples

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

Examples

parse(value) View Source

parse!(value) View Source

scale(size, unit_system \\ nil) View Source (since 1.1.0) scale(t(), nil | unit_system()) :: t()

Examples

subtract(size, other_size) View Source

subtract(size, other_size, as_unit_or_unit_system) View Source subtract(t(), t(), unit() | {:system, unit_system()}) :: 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_or_unit_system) View Source

add(t(), t(), unit() | {:system, unit_system()}) :: 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(bytes, as_unit_or_unit_system \\ {:system, :si}) View Source

from_bits(integer(), unit() | {:system, unit_system()}) :: t()

from_bytes(bytes, as_unit_or_unit_system \\ {:system, :si}) View Source

from_bytes(integer(), unit() | {:system, unit_system()}) :: t()

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

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

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

from_file!(Path.t(), unit() | {:system, unit_system()}) :: t() | no_return()

gt?(size, other_size) View Source (since 1.2.0)

gt?(t(), t()) :: boolean()

gteq?(size, other_size) View Source (since 1.2.0)

gteq?(t(), t()) :: boolean()

lt?(size, other_size) View Source (since 1.2.0)

lt?(t(), t()) :: boolean()

lteq?(size, other_size) View Source (since 1.2.0)

lteq?(t(), t()) :: boolean()

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

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

scale(size, unit_system \\ nil) View Source (since 1.1.0)

scale(t(), nil | unit_system()) :: t()

subtract(size, other_size, as_unit_or_unit_system) View Source

subtract(t(), t(), unit() | {:system, unit_system()}) :: t()