🥮 mooncakes.io

    bytesize

    an utility for human-readable bytes representations

    bytesize
    byte
    size
    format
    human-readable
    Download zip
    Author
    Version
    0.2.3
    License
    MIT
    Repository
    Last updated
    3 months ago
    Downloads
    40

    #justjavac/bytesize

    coverage

    @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

    source
    pub struct ByteSize {
      size : UInt64
    } derive(Compare, Default, Eq, Hash, 
    Debug    )

    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.
    impl Show for ByteSize

    ByteSize::as_u64

    source
    fn ByteSize::as_u64(self : ByteSize) -> UInt64

    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

    source
    fn ByteSize::b(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::debug_string(self : ByteSize) -> 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

    source
    fn ByteSize::display(self : 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

    source
    fn ByteSize::gb(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::gib(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::kb(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::kib(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::mb(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::mib(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::pb(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::pib(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::tb(size : UInt64) -> ByteSize

    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

    source
    fn ByteSize::tib(size : UInt64) -> ByteSize

    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.

    ByteSize::to_string

    source
    fn ByteSize::to_string(self : ByteSize) -> String

    Formats this value using the default IEC display style.

    This is equivalent to self.display().to_string() and produces strings such as 1 KiB, 419 MiB, or 2 PiB.

    Display

    source
    pub struct Display {
      byte_size : UInt64
      format : Format
    } derive(
    Debug    )

    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.
    impl Show for Display

    Display::iec

    source
    fn Display::iec(self : Display) -> Display

    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

    source
    fn Display::iec_short(self : Display) -> Display

    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

    source
    fn Display::new(byte_size : UInt64) -> Display

    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

    source
    fn Display::si(self : Display) -> Display

    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

    source
    fn Display::si_short(self : Display) -> Display

    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

    source
    fn Display::to_string(self : Display, precision? : Int) -> 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

    source
    pub enum Format {
      Iec
      IecShort
      Si
      SiShort
    } derive(
    Debug    )

    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.
    impl Show for Format

    Format::unit

    source
    fn Format::unit(self : Format) -> UInt64

    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

    source
    fn Format::unit_base(self : Format) -> Double

    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

    source
    fn Format::unit_prefixes(self : Format) -> String

    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

    source
    fn Format::unit_separator(self : Format) -> String

    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.

    Format::unit_suffix

    source
    fn Format::unit_suffix(self : Format) -> String

    Returns the suffix appended after the unit prefix.

    IEC long format uses iB, SI long format uses B, and the short formats omit the suffix entirely.
    let GB : UInt64

    Number of bytes in 1 gigabyte.

    GIB

    source
    let GIB : UInt64

    Number of bytes in 1 gibibyte.
    let KB : UInt64

    Number of bytes in 1 kilobyte.

    KIB

    source
    let KIB : UInt64

    Number of bytes in 1 kibibyte.
    let MB : UInt64

    Number of bytes in 1 megabyte.

    MIB

    source
    let MIB : UInt64

    Number of bytes in 1 mebibyte.
    let PB : UInt64

    Number of bytes in 1 petabyte.

    PIB

    source
    let PIB : UInt64

    Number of bytes in 1 pebibyte.
    let TB : UInt64

    Number of bytes in 1 terabyte.

    TIB

    source
    let TIB : UInt64

    Number of bytes in 1 tebibyte.
    fn gb(size : UInt64) -> UInt64

    Converts 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

    source
    fn gib(size : UInt64) -> UInt64

    Converts 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

    source
    fn ideal_unit_no_std(size : Double, unit : UInt64) -> Int

    Calculates 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.
    fn kb(size : UInt64) -> UInt64

    Converts 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

    source
    fn kib(size : UInt64) -> UInt64

    Converts 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.
    fn mb(size : UInt64) -> UInt64

    Converts 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

    source
    fn mib(size : UInt64) -> UInt64

    Converts 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.
    fn pb(size : UInt64) -> UInt64

    Converts 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

    source
    fn pib(size : UInt64) -> UInt64

    Converts 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.
    fn tb(size : UInt64) -> UInt64

    Converts 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

    source
    fn tib(size : UInt64) -> UInt64

    Converts 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

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io