bytesize

bytesize wraps a raw u64 byte count in a ByteSize newtype so that sizes carry their own semantics instead of being ambiguous integers. It provides SI (kB, MB, GB) and IEC (KiB, MiB, GiB) constructors and constants, arithmetic operator overloads (+, -, comparisons), a FromStr implementation for parsing human-written sizes like “1.5KiB” or “521TiB”, and configurable human-readable display formatting. #[no_std]-compatible by default with optional serde and arbitrary feature flags, it’s a small, focused utility that removes an entire class of off-by-one and unit-confusion bugs from any code that deals with disk, memory, or network sizes.

What You Get

• ByteSize newtype wrapping a u64, with constructors and constants for both SI units (kb, mb, gb, tb, pb) and IEC units (kib, mib, gib, tib, pib)
• Arithmetic operator overloads (+, -, ordering comparisons) so ByteSize values combine and compare like numbers
• FromStr parsing for human-written size strings such as "1.5KiB" or "521TiB", useful for CLI flags and config files
• Configurable Display formatting via .display().iec(), .display().si(), and .display().iec_short() for human-readable output
• Optional serde support for binary and human-readable (JSON) (de)serialization, and #[no_std] compatibility by default with an std feature flag

Common Use Cases

• Displaying file sizes, disk usage, or memory consumption to users in a consistent human-readable format
• Parsing size limits from CLI arguments or config files (e.g. “max upload size: 10MiB”) without hand-writing unit-conversion logic
• Passing byte counts between systems as strongly-typed values instead of raw integers, avoiding SI/IEC unit confusion
• Embedded or no_std environments that need byte-size semantics without pulling in the full Rust standard library

Under The Hood

Architecture - The crate is a small, focused newtype wrapper: src/lib.rs defines the ByteSize(u64) struct plus constant/constructor functions for each SI and IEC unit, src/parse.rs implements FromStr for string-to-ByteSize conversion, src/display.rs implements the configurable human-readable formatting (.display().iec()/.si()/.iec_short()), and src/serde.rs/src/arbitrary.rs are optional feature-gated modules for serde and arbitrary trait impls. There’s no runtime state or I/O — the entire crate is pure value transformation. Tech Stack - Pure Rust, #[no_std]-compatible by default (an ensure-no-std/ sub-crate exists specifically to CI-test the no_std build), targeting Rust 1.85+ edition 2021, with only optional dependencies (arbitrary, serde_core) gated behind feature flags — zero mandatory runtime dependencies. Code Quality - The project enforces rust-2018-idioms, future-incompatible, and nonstandard-style lints at deny level and missing-docs at warn, uses quickcheck for property-based testing of parsing/formatting round-trips, and divan for benchmarking display formatting performance; cargo_check_external_types metadata further constrains which external types are allowed to leak through the public API, a sign of deliberate API-surface discipline. API Design - Construction reads naturally (ByteSize::gib(518), ByteSize::mb(1) + ByteSize::kb(100)), comparisons and arithmetic work as expected between IEC and SI values, and the .display() builder pattern for output formatting keeps the common case (to_string()) simple while still exposing IEC/SI/short format choices for callers who need them.