File Size v2.1.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. 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 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.

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.
  • lte?/2 - Determines whether file size a <= b.
  • gt?/2 - Determines whether file size a > b.
  • gte?/2 - Determines whether file size a >= b.

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

iex> sizes = [~F(16 GB), ~F(100 Mbit), ~F(27.4 MB), ~F(16 Gbit)]
...> Enum.sort(sizes, &FileSize.lte?/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)

AtomSymbolNameFactor
:bitbitBits1
:kbitkbitKilobits1000
:mbitMbitMegabits1000^2
:gbitGBitGigabits1000^3
:tbitTBitTerabits1000^4
:pbitPBitPetabits1000^5
:ebitEBitExabits1000^6
:zbitZBitZetabits1000^7
:ybitYBitYottabits1000^8

IEC (International Electrotechnical Commission)

AtomSymbolNameFactor
:bitBitBits1
:kibitKibitKibibits1024
:mibitMibitMebibits1024^2
:gibitGibitGibibits1024^3
:tibitTibitTebibits1024^4
:pibitPibitPebibits1024^5
:eibitEibitExbibits1024^6
:zibitZibitZebibits1024^7
:yibitYibitYobibits1024^8

Byte-based

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

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

AtomSymbolNameFactor
:bBBytes1
:kbkBKilobytes1000
:mbMBMegabytes1000^2
:gbGBGigabytes1000^3
:tbTBTerabytes1000^4
:pbPBPetabytes1000^5
:ebEBExabytes1000^6
:zbZBZetabytes1000^7
:ybYBYottabytes1000^8

IEC (International Electrotechnical Commission)

AtomSymbolNameFactor
:bBBytes1
:kibKiBKibibytes1024
:mibMiBMebibytes1024^2
:gibGiBGibibytes1024^3
:tibTiBTebibytes1024^4
:pibPiBPebibytes1024^5
:eibEiBExbibytes1024^6
:zibZiBZebibytes1024^7
:yibYiBYobibytes1024^8

Link to this section Summary

Types

A type that defines the IEC bit and byte units.

A type that defines the SI bit and byte units.

t()

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

A type that is a union of the bit and byte unit types and FileSize.Units.Info.t/0.

A type that represents a unit symbol.

A type that contains the available unit systems.

A type that defines the value used to create a new file size.

Functions

Gets the configuration.

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

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

Determines whether two file sizes are equal.

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

Builds a new file size from the given number of bits, allowing conversion in the same step.

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

Builds a new file size from the given number of bits, allowing conversion in the same step.

Determines the size of the file at the given path.

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

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

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

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

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

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

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

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

Converts the given file size to the most appropriate unit. When no unit system is specified, the unit system of the source file size is used. If no unit system could be inferred from the size, the SI unit system is used.

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

Gets the normalized size from the given file size as integer.

Gets the value from the file size as float.

Link to this section Types

A type that defines the IEC bit and byte units.

A type that defines the SI bit and byte units.

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

A type that is a union of the bit and byte unit types and FileSize.Units.Info.t/0.

Link to this type

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

A type that represents a unit symbol.

Link to this type

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

A type that contains the available unit systems.

A type that defines the value used to create a new file size.

Link to this section Functions

Link to this function

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

Gets the configuration.

See FileSize.Calculable.add/2.

Link to this function

add(size, other_size, unit_or_unit_info_or_opts) View Source
add(t(), t(), unit() | Keyword.t()) :: t()

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

Options

When a keyword list is given, you must specify one of the following options.

  • :unit - Converts the file size to the given unit/0.
  • :system - Converts the file size to the given unit_system/0.

Examples

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), unit: :b)
#FileSize<"3000 B">

iex> FileSize.add(FileSize.new(1, :kb), FileSize.new(2, :kb), system: :iec)
#FileSize<"2.9296875 KiB">
Link to this function

compare(size, other_size) View Source

See FileSize.Comparable.compare/2.

Link to this function

convert(size, unit_or_unit_info_or_opts) View Source
convert(t(), unit() | Keyword.t()) :: t()

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

Options

When a keyword list is given, you must specify one of the following options.

  • :unit - Converts the file size to the given unit/0.
  • :system - Converts the file size to the given unit_system/0.

Examples

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

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

iex> FileSize.convert(FileSize.new(20, :kb), :kbit)
#FileSize<"160 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), unit: :unknown)
** (FileSize.InvalidUnitError) Invalid unit: :unknown

iex> FileSize.convert(FileSize.new(2, :b), system: :unknown)
** (FileSize.InvalidUnitSystemError) Invalid unit system: :unknown
Link to this function

equals?(size, other_size) View Source
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
Link to this function

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

See FileSize.Formatter.format/2.

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

Example

iex> FileSize.from_bits(2000)
#FileSize<"2000 bit">
Link to this function

from_bits(bits, unit_or_unit_info_or_opts) View Source
from_bits(value(), unit() | Keyword.t()) :: t()

Builds a new file size from the given number of bits, allowing conversion in the same step.

Options

When a keyword list is given, you must specify one of the following options.

  • :convert - Converts the file size to the given unit/0.
  • :scale - Scales and converts the file size to an appropriate unit in the specified unit_system/0.

Examples

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

iex> FileSize.from_bits(16, scale: :unknown)
** (FileSize.InvalidUnitSystemError) Invalid unit system: :unknown

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

iex> FileSize.from_bits(1600, :kbit)
#FileSize<"1.6 kbit">

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

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

Example

iex> FileSize.from_bytes(2000)
#FileSize<"2000 B">
Link to this function

from_bytes(bytes, unit_or_unit_info_or_opts) View Source
from_bytes(value(), unit() | Keyword.t()) :: t()

Builds a new file size from the given number of bits, allowing conversion in the same step.

Options

When a keyword list is given, you must specify one of the following options.

  • :convert - Converts the file size to the given unit/0.
  • :scale - Scales and converts the file size to an appropriate unit in the specified unit_system/0.

Examples

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

iex> FileSize.from_bytes(16, scale: :unknown)
** (FileSize.InvalidUnitSystemError) Invalid unit system: :unknown

iex> FileSize.from_bytes(2, convert: :bit)
#FileSize<"16 bit">

iex> FileSize.from_bytes(1600, :kb)
#FileSize<"1.6 kB">

iex> FileSize.from_bytes(16, convert: :unknown)
** (FileSize.InvalidUnitError) Invalid unit: :unknown
Link to this function

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

Determines the size of the file at the given path.

Options

When a keyword list is given, you must specify one of the following options.

  • :convert - Converts the file size to the given unit/0.
  • :scale - Scales and converts the file size to an appropriate unit in the specified unit_system/0.

Examples

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

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

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

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

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

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

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

Options

When a keyword list is given, you must specify one of the following options.

  • :convert - Converts the file size to the given unit/0.
  • :scale - Scales and converts the file size to an appropriate unit in the specified unit_system/0.

Examples

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

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

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

iex> FileSize.from_file!("path/to/my/file.txt", system: :iec)
#FileSize<"133.7 KiB">

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

gt?(size, other_size) View Source (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
Link to this function

gte?(size, other_size) View Source (since 2.0.0)
gte?(t(), t()) :: boolean()

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

Examples

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

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

iex> FileSize.gte?(FileSize.new(1, :b), FileSize.new(2, :b))
false
Link to this function

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

This function is deprecated. Use gte?/2 instead.

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

Link to this function

lt?(size, other_size) View Source (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
Link to this function

lte?(size, other_size) View Source (since 2.0.0)
lte?(t(), t()) :: boolean()

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

Examples

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

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

iex> FileSize.lte?(FileSize.new(2, :b), FileSize.new(1, :b))
false
Link to this function

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

This function is deprecated. Use lte?/2 instead.

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

Link to this function

new(value, unit_or_unit_info \\ :b) View Source
new(value(), 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 KiB">

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

See FileSize.Parser.parse/1.

See FileSize.Parser.parse!/1.

Link to this function

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

Converts the given file size to the most appropriate unit. When no unit system is specified, the unit system of the source file size is used. If no unit system could be inferred from the size, the SI unit system is used.

Examples

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

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

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

iex> FileSize.scale(FileSize.new(2000, :b), :unknown)
** (FileSize.InvalidUnitSystemError) Invalid unit system: :unknown
Link to this function

subtract(size, other_size) View Source

See FileSize.Calculable.subtract/2.

Link to this function

subtract(size, other_size, unit_or_unit_info_or_opts) View Source
subtract(t(), t(), unit() | Keyword.t()) :: t()

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

Options

When a keyword list is given, you must specify one of the following options.

  • :unit - Converts the file size to the given unit/0.
  • :system - Converts the file size to the given unit_system/0.

Examples

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

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

iex> FileSize.subtract(FileSize.new(3, :kb), FileSize.new(1, :kb), system: :iec)
#FileSize<"1.953125 KiB">
Link to this function

to_integer(size) View Source (since 2.0.0)
to_integer(t()) :: integer()

Gets the normalized size from the given file size as integer.

Example

iex> FileSize.to_integer(FileSize.new(2, :kbit))
2000
Link to this function

value_to_float(size) View Source (since 2.1.0)
value_to_float(t()) :: float()

Gets the value from the file size as float.

Examples

iex> FileSize.value_to_float(FileSize.new(2, :kbit))
2.0

iex> FileSize.value_to_float(FileSize.new(2.3, :kbit))
2.3