File Size v2.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. 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.
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.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)
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
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
.
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.
Link to this section Types
iec_unit()
View Source
iec_unit() :: FileSize.Bit.iec_unit() | FileSize.Byte.iec_unit()
iec_unit() :: FileSize.Bit.iec_unit() | FileSize.Byte.iec_unit()
A type that defines the IEC bit and byte units.
si_unit()
View Source
si_unit() :: FileSize.Bit.si_unit() | FileSize.Byte.si_unit()
si_unit() :: FileSize.Bit.si_unit() | FileSize.Byte.si_unit()
A type that defines the SI bit and byte units.
t()
View Source
t() :: FileSize.Bit.t() | FileSize.Byte.t()
t() :: FileSize.Bit.t() | FileSize.Byte.t()
A type that is a union of the bit and byte types.
unit()
View Source
unit() :: iec_unit() | si_unit() | FileSize.Units.Info.t()
unit() :: iec_unit() | si_unit() | FileSize.Units.Info.t()
A type that is a union of the bit and byte unit types and
FileSize.Units.Info.t/0
.
unit_symbol()
View Source
unit_symbol() :: String.t()
unit_symbol() :: String.t()
A type that represents a unit symbol.
unit_system()
View Source
unit_system() :: :iec | :si
unit_system() :: :iec | :si
A type that contains the available unit systems.
value() View Source
A type that defines the value used to create a new file size.
Link to this section Functions
__config__()
View Source
__config__() :: Keyword.t()
__config__() :: Keyword.t()
Gets the configuration.
add(size, other_size) View Source
add(size, other_size, unit_or_unit_info_or_opts) View Source
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 givenunit/0
.:system
- Converts the file size to the givenunit_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">
compare(size, other_size) View Source
convert(size, unit_or_unit_info_or_opts) View Source
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 givenunit/0
.:system
- Converts the file size to the givenunit_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
equals?(size, other_size) View Source
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
from_bits(bits) View Source
Builds a new file size from the given number of bits.
Example
iex> FileSize.from_bits(2000)
#FileSize<"2000 bit">
from_bits(bits, unit_or_unit_info_or_opts) View Source
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 givenunit/0
.:scale
- Scales and converts the file size to an appropriate unit in the specifiedunit_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
from_bytes(bytes) View Source
Builds a new file size from the given number of bits.
Example
iex> FileSize.from_bytes(2000)
#FileSize<"2000 B">
from_bytes(bytes, unit_or_unit_info_or_opts) View Source
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 givenunit/0
.:scale
- Scales and converts the file size to an appropriate unit in the specifiedunit_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
from_file(path, unit_or_unit_info_or_opts \\ :b)
View Source
from_file(Path.t(), unit() | Keyword.t()) ::
{:ok, t()} | {:error, File.posix()}
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 givenunit/0
.:scale
- Scales and converts the file size to an appropriate unit in the specifiedunit_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}
from_file!(path, unit_or_unit_info_or_opts \\ :b) View Source
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 givenunit/0
.:scale
- Scales and converts the file size to an appropriate unit in the specifiedunit_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
gt?(size, other_size) View Source (since 1.2.0)
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
gte?(size, other_size) View Source (since 2.0.0)
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
gteq?(size, other_size) View Source (since 1.2.0)
Determines whether the first file size is less or equal to than the second one.
lt?(size, other_size) View Source (since 1.2.0)
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
lte?(size, other_size) View Source (since 2.0.0)
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
lteq?(size, other_size) View Source (since 1.2.0)
Determines whether the first file size is less or equal to than the second one.
new(value, unit_or_unit_info \\ :b) View Source
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">
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()
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
subtract(size, other_size) View Source
subtract(size, other_size, unit_or_unit_info_or_opts) View Source
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 givenunit/0
.:system
- Converts the file size to the givenunit_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">
to_integer(size) View Source (since 2.0.0)
Gets the normalized size from the given file size as integer.
Example
iex> FileSize.to_integer(FileSize.new(2, :kbit))
2000