bytesize
an utility for human-readable bytes representations
bytesize
byte
size
format
human-readable
moon add justjavac/bytesize@0.2.3
Download zipAuthor
Version
0.2.3
License
MIT
Repository
Last updated
2 months ago
Downloads
32
README#justjavac/bytesize
@bytesize provides a small ByteSize wrapper for converting exact byte counts
and formatting them with either IEC or SI units.
#Convert raw units
///|
test "raw unit helpers return exact byte counts" {
assert_eq(@bytesize.kb(1), 1_000UL)
assert_eq(@bytesize.mb(1), 1_000_000UL)
assert_eq(@bytesize.gb(1), 1_000_000_000UL)
assert_eq(@bytesize.tb(1), 1_000_000_000_000UL)
assert_eq(@bytesize.pb(1), 1_000_000_000_000_000UL)
assert_eq(@bytesize.kib(1), 1_024UL)
assert_eq(@bytesize.mib(1), 1_048_576UL)
assert_eq(@bytesize.gib(1), 1_073_741_824UL)
assert_eq(@bytesize.tib(1), 1_099_511_627_776UL)
assert_eq(@bytesize.pib(1), 1_125_899_906_842_624UL)
}#ByteSize
Semantic wrapper around a raw byte count.
ByteSize stores the canonical value in bytes while exposing constructors,
comparisons, arithmetic traits, and formatting helpers for SI and IEC output.
#ByteSize::as_u64
Returns the underlying byte count as a primitive UInt64.
This is useful when an external API expects a raw integer or when you need
to perform calculations outside the ByteSize wrapper.
#ByteSize::b
Wraps an exact byte count in ByteSize.
This constructor does not perform any unit conversion. Use it when you
already have a byte count and want access to ByteSize formatting,
comparison, and arithmetic helpers.
#ByteSize::debug_string
Formats this value with both human-readable text and the raw byte count.
The resulting string is intended for debugging and logs, where seeing the
friendly unit and the exact byte total at the same time is helpful.
#ByteSize::display
Returns a formatting wrapper for this byte size.
The returned Display starts in IEC mode, so calling to_string on it will
produce output like 1 KiB unless you switch to an SI variant first.
#ByteSize::gb
Constructs a ByteSize from a decimal gigabyte count.
This constructor uses SI scaling and returns a value that can be compared,
formatted, or combined with other ByteSize values.
#ByteSize::gib
Constructs a ByteSize from a binary gibibyte count.
This constructor uses IEC scaling and is useful when you want to preserve
the distinction between binary sizes and decimal storage labels.
#ByteSize::kb
Constructs a ByteSize from a decimal kilobyte count.
The input follows the SI definition (1 kB = 1000 bytes). This is the
wrapper-producing counterpart to kb, so it is convenient when you want the
converted value together with ByteSize display and comparison helpers.
#ByteSize::kib
Constructs a ByteSize from a binary kibibyte count.
The input follows the IEC definition (1 KiB = 1024 bytes). Choose this
constructor when you want binary units and the ergonomic ByteSize API.
#ByteSize::mb
Constructs a ByteSize from a decimal megabyte count.
The input is interpreted in SI units, making it a good fit for disk, file,
and transfer sizes that are normally reported in base-10 units.
#ByteSize::mib
Constructs a ByteSize from a binary mebibyte count.
The input is interpreted in IEC units, which is useful for measurements that
are naturally expressed as powers of two, such as memory sizes.
#ByteSize::pb
Constructs a ByteSize from a decimal petabyte count.
This is the SI counterpart to ByteSize::pib and is appropriate for
extremely large base-10 byte quantities.
#ByteSize::pib
Constructs a ByteSize from a binary pebibyte count.
This constructor uses IEC scaling for extremely large binary quantities and
keeps the result available through the ByteSize API.
#ByteSize::tb
Constructs a ByteSize from a decimal terabyte count.
Use this constructor for very large SI quantities when you still want to
keep the value strongly typed as ByteSize.
#ByteSize::tib
Constructs a ByteSize from a binary tebibyte count.
This constructor preserves IEC semantics for very large binary quantities
while still returning a regular ByteSize wrapper.
#Display
Formatting wrapper for byte sizes.
Display stores the raw byte count together with the selected Format.
Newly created instances default to IEC formatting until you switch styles.
#Display::iec
Switches the display wrapper to IEC long format.
This produces output such as 11.8 MiB, with a separating space and the
binary iB suffix.
#Display::iec_short
Switches the display wrapper to IEC short format.
This produces compact output such as 11.8M. The short form is convenient
for narrow UI surfaces and shell output that is sorted with sort -h.
#Display::new
Creates a display wrapper with the default IEC format.
The provided byte_size is stored unchanged. Call si, si_short, or
iec_short on the returned value when you want a different rendering style.
#Display::si
Switches the display wrapper to SI long format.
This produces output such as 12.3 MB, which matches the decimal unit
system commonly used by storage devices and transfer rates.
#Display::si_short
Switches the display wrapper to SI short format.
This produces compact decimal strings such as 12.3M, which are useful
when you want SI semantics but minimal visual noise.
#Display::to_string
Formats the stored byte count as a human-readable string.
Values smaller than the first unit are rendered as bytes, while larger
values are promoted to the most suitable unit for the active Format.
precision controls how many decimal places are kept after rounding.
#Format
Formatting style used when rendering a ByteSize.
Format controls the unit family (IEC or SI), whether separators are kept,
and how suffixes such as B or iB are produced.
#Format::unit
Returns the numeric unit step for this format.
IEC formats scale by 1024, while SI formats scale by 1000. Display
uses this value to decide when to promote bytes to the next unit.
#Format::unit_base
Returns the logarithmic base used for unit selection.
This value matches the natural logarithm of the format's unit step and is
used by Display::to_string to choose the best prefix efficiently.
#Format::unit_prefixes
Returns the sequence of unit prefixes for this format.
IEC formats use uppercase binary prefixes such as K, M, and G, while
SI formats use the decimal sequence beginning with lowercase k.
#Format::unit_separator
Returns the separator inserted between the numeric value and unit text.
Long formats keep a space, such as 1 KiB or 1 MB, while the short
formats omit it to produce strings such as 1K and 1M.
#gb
fn gb(size : UInt64) -> UInt64Converts a decimal gigabyte count into a raw byte count.
The input is interpreted with SI units (1 GB = 1_000_000_000 bytes), so it
matches storage sizes that are commonly reported by disks and networks.
#gib
fn gib(size : UInt64) -> UInt64Converts a binary gibibyte count into a raw byte count.
The input is interpreted with IEC units (1 GiB = 1_073_741_824 bytes),
which is the unit family typically used for memory-style measurements.
#ideal_unit_no_std
fn ideal_unit_no_std(size : Double, unit : UInt64) -> IntCalculates the 1-based unit index using repeated division only.
This helper mirrors the format-selection logic without relying on logarithms,
which makes it useful in restricted environments or for validation tests.
#kb
fn kb(size : UInt64) -> UInt64Converts a decimal kilobyte count into a raw byte count.
This helper uses the SI definition (1 kB = 1000 bytes) and returns the
primitive UInt64 value directly. Use ByteSize::kb when you want the same
converted value wrapped in ByteSize.
#kib
fn kib(size : UInt64) -> UInt64Converts a binary kibibyte count into a raw byte count.
This helper uses the IEC definition (1 KiB = 1024 bytes) and returns the
primitive UInt64 value directly. Use ByteSize::kib when you want the
converted value as a ByteSize.
#mb
fn mb(size : UInt64) -> UInt64Converts a decimal megabyte count into a raw byte count.
This helper uses the SI definition (1 MB = 1_000_000 bytes) and is useful
when an API expects a primitive byte count instead of a ByteSize wrapper.
#mib
fn mib(size : UInt64) -> UInt64Converts a binary mebibyte count into a raw byte count.
This helper uses the IEC definition (1 MiB = 1_048_576 bytes) and returns
a plain UInt64. Use ByteSize::mib when you want formatting helpers too.
#pb
fn pb(size : UInt64) -> UInt64Converts a decimal petabyte count into a raw byte count.
This helper is useful for large SI quantities such as storage capacities and
data transfer reports that are expressed in base-10 units.
#pib
fn pib(size : UInt64) -> UInt64Converts a binary pebibyte count into a raw byte count.
This helper uses IEC scaling and returns the exact byte count as UInt64,
which is useful for large memory-style quantities.
#tb
fn tb(size : UInt64) -> UInt64Converts a decimal terabyte count into a raw byte count.
This helper keeps the result as a primitive UInt64, making it convenient
when you only need the exact byte total and not the ByteSize API.
#tib
fn tib(size : UInt64) -> UInt64Converts a binary tebibyte count into a raw byte count.
This helper applies IEC scaling (1 TiB = 1024 GiB) and returns the exact
number of bytes without wrapping it in ByteSize.
Source Files
an utility for human-readable bytes representations
bytesizebytesizeformathuman-readable
0.2.3
MIT
Updated 2 months ago
32 downloads