kex docs Standard Library 0.4.0-alpha kex.run ↗

Units.Data

module Units.Data

Data sizes: bytes, kilobytes, and their binary counterparts.

Opt-in: nothing here is in scope until using Units.Data.

using Units.Data

main do
  IO.printLine(1500.megabytes.to(String))              # prints: 1500.0 MB
  IO.printLine(1500000000.byteSize.to(String, in: Giga)) # prints: 1.5 GB
end

Both families are here and they are not the same: KB is 1000 bytes, KiB is 1024. Values built from either convert freely, because both are counted in bytes underneath, so 1.gibibytes.convertTo(MiB) answers 1024 MiB.

Every value is a Measure from the prelude, so its arithmetic, comparison and to(String) apply unchanged.

type DataUnit

The data units this module names: decimal (KB, MB, GB, TB) and binary (KiB, MiB, GiB, TiB), plus the plain byte B.

1.KB   # 1000 bytes
1.KiB  # 1024 bytes

Variants

  • B
  • KB
  • MB
  • GB
  • TB
  • KiB
  • MiB
  • GiB
  • TiB

type DataPrefix

A decimal prefix to render a size at: Kilo means KB, Mega means MB, Giga means GB.

Data prefixes select their standard decimal byte unit, so Mega is MB rather than a prefix applied twice to the measure's existing unit.

Variants

  • Kilo
  • Mega
  • Giga

make DataUnit implements Unit

factor

factor(@B)

symbol

symbol(@B)

make UnitDefinition implements Unit

make Measure

function size

value of the given data unit, as a Measure.

The general constructor the named ones below are written on. Reach for megabytes, kibibytes and friends when the unit is known at the call site.

size(value, unit)
Parameters
value Number
the quantity
unit DataUnit
the unit it is counted in

Returns: Measure — the size

Examples
size(4096, B).to(String)     # => "4096.0 B"
size(1.5, MB).to(String)     # => "1.5 MB"

function convertTo

Converts a size to another data unit.

Decimal and binary units convert freely, because both are counted in bytes underneath. A measure of some other dimension is an Error.

convertTo(measure, unit)
Parameters
measure Measure
the size to convert
unit DataUnit
the unit to convert to

Returns: Result<Measure, String> — the converted size, or why it could not be

Examples
1.gibibytes.convertTo(MiB).map { |m| m.to(String) }   # => Ok("1024.0 MiB")
2.gigabytes.convertTo(MB).map { |m| m.to(String) }    # => Ok("2000.0 MB")

function to

Renders a size at a chosen decimal prefix.

Data prefixes select their standard decimal byte unit. They are targets for formatting, so Mega means MB rather than a prefix applied twice to the measure's existing unit. A measure that is not a data size answers None.

to(measure, String, in)
Parameters
String Type
the target type
in DataPrefix
the prefix to display at

Returns: String? — the rendered size, or None

Examples
1500000000.byteSize.to(String, in: Giga)   # => Just("1.5 GB")
1500000.byteSize.to(String, in: Mega)      # => Just("1.5 MB")

function byteSize

value bytes.

Named byteSize rather than bytes, which String already uses for its UTF-8 encoding.

byteSize(value)
Parameters
value Number
the quantity

Returns: Measure — the size

Examples
4096.byteSize.to(String)   # => "4096.0 B"

Reporting a file's size

FS.File.size(path).map { |n| n.byteSize.to(String, in: Mega) }

function kilobytes

value kilobytes, 1000 bytes each.

kilobytes(value)
Parameters
value Number
the quantity

Returns: Measure — the size

Examples
5.kilobytes.to(String)   # => "5.0 KB"

function megabytes

value megabytes, 1000000 bytes each.

megabytes(value)
Parameters
value Number
the quantity

Returns: Measure — the size

Examples
1500.megabytes.to(String)   # => "1500.0 MB"

function gigabytes

value gigabytes, 10^9 bytes each.

gigabytes(value)
Parameters
value Number
the quantity

Returns: Measure — the size

Examples
2.gigabytes.convertTo(MB).map { |m| m.to(String) }   # => Ok("2000.0 MB")

function terabytes

value terabytes, 10^12 bytes each.

terabytes(value)
Parameters
value Number
the quantity

Returns: Measure — the size

Examples
2.terabytes.to(String)   # => "2.0 TB"

function kibibytes

value kibibytes, 1024 bytes each.

kibibytes(value)
Parameters
value Number
the quantity

Returns: Measure — the size

Examples
1024.kibibytes.to(String)   # => "1024.0 KiB"

function mebibytes

value mebibytes, 1024^2 bytes each.

mebibytes(value)
Parameters
value Number
the quantity

Returns: Measure — the size

Examples
3.mebibytes.to(String)   # => "3.0 MiB"

function gibibytes

value gibibytes, 1024^3 bytes each.

gibibytes(value)
Parameters
value Number
the quantity

Returns: Measure — the size

Examples
1.gibibytes.convertTo(MiB).map { |m| m.to(String) }   # => Ok("1024.0 MiB")

function tebibytes

value tebibytes, 1024^4 bytes each.

tebibytes(value)
Parameters
value Number
the quantity

Returns: Measure — the size

Examples
1.tebibytes.to(String)   # => "1.0 TiB"