Gets the configuration.

See FileSize.Calculable.add/2.

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">

Compares two file sizes and returns an atom indicating whether the first value is less than, greater than or equal to the second one.

Example

iex> FileSize.compare(FileSize.new(2, :b), FileSize.new(16, :bit))
:eq

iex> FileSize.compare(FileSize.new(1, :b), FileSize.new(16, :bit))
:lt

iex> FileSize.compare(FileSize.new(3, :b), FileSize.new(16, :bit))
:gt

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

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

Formats a file size in a human-readable format, allowing customization of the formatting.

Options

• :symbols - Allows using your own unit symbols. Must be a map that contains the unit names as keys (as defined by FileSize.unit/0) and the unit symbol strings as values. Missing entries in the map are filled with the internal unit symbols from FileSize.Units.list/0.

Other options customize the number format and are forwarded to Number.Delimit.number_to_delimited/2. The default precision for numbers is 0.

Global Configuration

You can also define your custom symbols globally.

config :file_size, :symbols, %{b: "Byte", kb: "KB"}

The same is possible for number formatting.

config :file_size, :number_format, precision: 2, delimiter: ",", separator: "."

Or globally for the number library.

config :number, delimit: [precision: 2, delimiter: ",", separator: "."]

Examples

iex> FileSize.format(FileSize.new(32, :kb))
"32 kB"

iex> FileSize.format(FileSize.new(2048.2, :mb))
"2,048 MB"

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

Example

iex> FileSize.from_bits(2000)
#FileSize<"2000 bit">

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">

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

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}

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", unit: "KiB")
#FileSize<"133.7 KiB">

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

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

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

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

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

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">

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

Converts the given value into a value of type FileSize.t/0. Returns a tuple containing the status and value or error.

Converts the given value into a value of type FileSize.t/0. Returns the value on success or raises FileSize.ParseError on error.

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.862645149230957 GiB">

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

See FileSize.Calculable.subtract/2.

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">

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

Example

iex> FileSize.to_integer(FileSize.new(2, :kbit))
2000

Formats the given size ignoring all user configuration. The result of this function can be passed back to FileSize.parse/1 and is also used by the implementations of the Inspect and String.Chars protocols.

Example

iex> FileSize.to_string(FileSize.new(32.2, :kb))
"32.2 kB"

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