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.megabyte.to(String)) # prints: 1500.0 MB
IO.printLine(1500000000.byte.to(String, in: GB).or("")) # prints: 1.5 GB
endBoth 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.gibibyte.convertTo(MiB) answers 1024 MiB.
Numeric constructors use singular names, as in Units.SI: 5.megabyte and 2.mebibyte. byteSize is an alias for byte.
File and payload APIs return integer byte counts. Wrap those counts with byte to convert or display them as measurements:
FS.File.size("report.pdf").map { |n| n.byte.showValue }
Binary.fromBytes([104, 105]).length.byte.to(String) # => Just("2.0 B")
"é".bytes.count.byte.to(String) # => Just("2.0 B")To display a size in another unit, decimal or binary, name the unit:
1048576.byte.to(String, in: MiB) # => Just("1.0 MiB")
4312.byte.to(String, in: KB, format: Number.format`#.#`) # => Just("4.3 KB")
1048576.byte.convertTo(MiB).map { |m| m.showValue } # => Ok("1.0 MiB")Compare an integer byte count directly with a data-size threshold:
30000001 > 30.megabyte # => true
1048576 <= 1.mebibyte # => true<, >, <=, and >= work with the count on either side. A time or SI measure is not a byte threshold and raises an error.
Every value is a Measure from the prelude, so its arithmetic and to(String) apply unchanged.
size
size(value: Number, unit: DataUnit) -> Measurevalue of the given data unit, as a Measure.
The general constructor the named ones below are written on. Reach for megabyte, kibibyte and friends when the unit is known at the call site.
Parameters
value- the quantity
unit- the unit it is counted in
Returns the size
Examples
size(4096, B).to(String) # => Just("4096.0 B")
size(1.5, MB).to(String) # => Just("1.5 MB")convertTo
convertTo(measure: Measure, unit: DataUnit) -> Result<Measure, String>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.
Parameters
measure- the size to convert
unit- the unit to convert to
Returns the converted size, or why it could not be
Examples
1.gibibyte.convertTo(MiB).map { |m| m.showValue } # => Ok("1024.0 MiB")
2.gigabyte.convertTo(MB).map { |m| m.showValue } # => Ok("2000.0 MB")byteSize
byteSize(value: Number) -> Measurevalue bytes.
Named byteSize rather than bytes, which String already uses for its UTF-8 encoding.
Parameters
value- the quantity
Returns the size
Examples
4096.byteSize.to(String) # => Just("4096.0 B")Reporting a file's size
FS.File.size("report.pdf").map { |n| n.byte.showValue }byte
byte(value: Number) -> Measurevalue bytes, as a Measure.
Use this with byte counts from FS.File.size or Binary.length.
Parameters
value- the byte count
Returns the size
Examples
A binary payload's size
let payload = Binary.fromBytes([104, 105])
payload.length.byte.to(String) # => Just("2.0 B")kilobyte
kilobyte(value: Number) -> Measurevalue kilobytes, 1000 bytes each.
Parameters
value- the quantity
Returns the size
Examples
5.kilobyte.to(String) # => Just("5.0 KB")megabyte
megabyte(value: Number) -> Measurevalue megabytes, 1000000 bytes each.
Parameters
value- the quantity
Returns the size
Examples
1500.megabyte.to(String) # => Just("1500.0 MB")gigabyte
gigabyte(value: Number) -> Measurevalue gigabytes, 10^9 bytes each.
Parameters
value- the quantity
Returns the size
Examples
2.gigabyte.convertTo(MB).map { |m| m.showValue } # => Ok("2000.0 MB")terabyte
terabyte(value: Number) -> Measurevalue terabytes, 10^12 bytes each.
Parameters
value- the quantity
Returns the size
Examples
2.terabyte.to(String) # => Just("2.0 TB")kibibyte
kibibyte(value: Number) -> Measurevalue kibibytes, 1024 bytes each.
Parameters
value- the quantity
Returns the size
Examples
1024.kibibyte.to(String) # => Just("1024.0 KiB")mebibyte
mebibyte(value: Number) -> Measurevalue mebibytes, 1024^2 bytes each.
Parameters
value- the quantity
Returns the size
Examples
3.mebibyte.to(String) # => Just("3.0 MiB")type DataUnit
The data units this module names: decimal (KB, MB, GB, TB) and binary (KiB, MiB, GiB, TiB), plus the plain byte B.
size(1, KB).canonical # => 1000.0 bytes
size(1, KiB).canonical # => 1024.0 bytesVariants
BKBMBGBTBKiBMiBGiBTiB
Implements Unit.
Functions
extends UnitDefinition
More functions for UnitDefinition, added by this module.
Implements Unit.
extends Measure
More functions for Measure, added by this module.
Displaying a size in another data unit: the prelude's to(String, in:), for this module's units.
to
to(String: Type, in: DataUnit, format: NumberFormat) -> String?Renders a size in another data unit, decimal or binary.
A measure that is not a data size answers None.
Parameters
String- the target type
in- the unit to display in
Returns the rendered size, or None
Examples
1500000000.byte.to(String, in: GB) # => Just("1.5 GB")
1048576.byte.to(String, in: MiB) # => Just("1.0 MiB")
1.second.to(String, in: MB) # => Noneextends Integer
More functions for Integer, added by this module.
Compares an integer byte count with a data-size threshold.
File and binary sizes stay integers. Import this module to use data units directly in comparisons; only data measures are accepted as thresholds.
Examples
Rejecting an oversized file
FS.File.size("report.pdf").map { |count| count > 30.megabyte }Checking a payload
Binary.fromBytes([104, 105]).length < 1.kibibyte # => true