humanize_proper 0.1.0

Dependency-free, no_std formatting of numbers with SI/binary unit prefixes and of durations
Documentation
  • Coverage
  • 100%
    40 out of 40 items documented9 out of 9 items with examples
  • Size
  • Source code size: 72.7 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 918.7 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 9s Average build duration of successful builds.
  • all releases: 6s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • daniel-x/humanize_proper
    1 0 1
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • daniel-x

humanize_proper

Human readable formatting of numbers and durations for Rust. No dependencies, #![no_std], no allocation, no unsafe.

Numbers

Binary (1024-wise) and decimal (1000-wise) unit prefixes. Byte formatting is the default, the _no_unit variants leave the B out.

use humanize_proper::{bin, bin_no_unit, dec, NumFmt};

assert_eq!(bin(1536).to_string(), "1.5KiB");
assert_eq!(dec(1500).to_string(), "1.5kB");
assert_eq!(bin_no_unit(1536).to_string(), "1.5Ki");

assert_eq!(NumFmt::bin().space(true).fmt(1536).to_string(), "1.5 KiB");
assert_eq!(NumFmt::bin().jedec().fmt(1536).to_string(), "1.5KB");
assert_eq!(NumFmt::dec().unit("Hz").fmt(1_500_000).to_string(), "1.5MHz");

Integers are formatted with exact u128 arithmetic, so rounding rolls over correctly and even u128 inputs stay precise:

use humanize_proper::{bin, dec};

assert_eq!(dec(999_999u64).to_string(), "1MB");
assert_eq!(bin(u64::MAX).to_string(), "16EiB");

Options

NumFmt builder, all methods const:

Method Effect Default
NumFmt::bin() base 1024, IEC prefixes, unit B, no space 1536 -> "1.5KiB"
NumFmt::dec() base 1000, SI prefixes, unit B, no space 1500 -> "1.5kB"
.base(Base) switches the base, keeping everything else
.space(bool) space between number and prefix false
.unit(&'static str) unit appended after the prefix "B"
.no_unit() drop the unit
.prefixes(Prefixes), .iec(), .jedec() spelling of the binary prefixes Iec
.sig_digits(u8) significant digits, clamped to 1..=15 3
.trim_zeros(bool) drop trailing fraction zeros and a bare . true
.fmt(value) bind a value, yielding a Display

Prefixes

Table Prefixes
SI, base 1000 k M G T P E Z Y R Q
IEC, base 1024 Ki Mi Gi Ti Pi Ei Zi Yi Ri Qi
JEDEC, base 1024 K M G T P E Z Y R Q

Prefixes only affects base 1024; base 1000 always uses the SI table with its lowercase k.

Rounding and precision

  • Rounding is half-up and may roll over into the next prefix, e.g. 999_999 -> "1MB".
  • The digit count applies to the integer part, so sig_digits never shortens it: at 1 significant digit, 999 still prints as 999B.
  • Values below 1 carry sig_digits - 1 fraction digits, e.g. 0.125 -> "0.13B". Leading zeros of the fraction are not counted as significant.
  • NaN prints as NaN, infinities as inf and -inf, all three without prefix or unit.
  • Magnitudes beyond the largest prefix, reachable only with floats, print their mantissa plainly.

Accepted input

Every primitive integer type plus f32 and f64, through the ToValue trait. Negative values are printed as - followed by the magnitude. Floats with an exact integer value take the exact integer path.

Durations

The default style is 32y007d_05h01m05s. Leading units that are zero are dropped, _ separates the date group from the time group.

use humanize_proper::{dur, DurFmt, TimeUnit, Zeros};

assert_eq!(dur(1_000_000_000u64).to_string(), "31y251d_13h21m28s");
assert_eq!(dur(3665u64).to_string(), "01h01m05s");

assert_eq!(DurFmt::new().zeros(Zeros::TrimAll).fmt(3665u64).to_string(), "1h1m5s");
assert_eq!(DurFmt::new().zeros(Zeros::TrimLargest).fmt(3665u64).to_string(), "1h01m05s");
assert_eq!(DurFmt::new().smallest(TimeUnit::Min).fmt(3665u64).to_string(), "01h01m");

The seconds field carries an optional fraction, from milliseconds down to attoseconds. Since core::time::Duration stops at nanoseconds, the crate has its own Dur type for the finer steps.

use humanize_proper::{Dur, DurFmt, Frac};

let d = Dur::from_nanos(65_123_456_789);
assert_eq!(DurFmt::new().frac(Frac::Millis).fmt(d).to_string(), "01m05.123s");
assert_eq!(DurFmt::new().frac(Frac::Nanos).fmt(d).to_string(), "01m05.123456789s");
assert_eq!(
    DurFmt::new().frac(Frac::Attos).fmt(Dur::from_attos(1)).to_string(),
    "00.000000000000000001s",
);

Options

DurFmt builder, all methods const:

Method Effect Default
DurFmt::new() the default style 32y007d_05h01m05s
.zeros(Zeros) zero padding mode Pad
.frac(Frac) fractional second precision Secs
.frac_digits(u8) arbitrary fraction width, 0..=18 0
.frac_sep(Option<&'static str>) group fraction digits in threes None
.sep(&'static str), .no_sep() date/time group separator "_"
.smallest(TimeUnit) smallest printed unit, truncating Sec
.secs_per_year(u64) length of a year in seconds 31_556_952
.fmt(duration) bind a duration, yielding a Display

Zero padding

Variant 5h 1m 5s
Zeros::Pad, the default 05h01m05s
Zeros::TrimAll 5h1m5s
Zeros::TrimLargest 5h01m05s

Padding uses the natural width of each unit: 3 digits for days, 2 for hours, minutes and seconds. Years are unbounded and never padded.

Fractional seconds

Variant Digits 65.123456789012345678 s
Frac::Secs, the default 0 01m05s
Frac::Millis 3 01m05.123s
Frac::Micros 6 01m05.123456s
Frac::Nanos 9 01m05.123456789s
Frac::Picos 12 01m05.123456789012s
Frac::Femtos 15 01m05.123456789012345s
Frac::Attos 18 01m05.123456789012345678s

The fraction is truncated rather than rounded, matching what .smallest(..) does, and it is only printed when the smallest printed unit is s. .frac_sep(Some("_")) groups the digits in threes, which the 18 digit precisions need to stay readable.

Details

  • A year is 365.2425 days, which is exactly 31_556_952 seconds, so day counts run 0..=365 and arithmetic stays exact at second granularity. Override it with .secs_per_year(u64).
  • The _ appears only when both the date group and the time group are present.
  • Negative durations are prefixed with -. Zero carries no sign, so Dur::ZERO.neg() == Dur::ZERO.

Accepted input

Dur, core::time::Duration, u32, u64, i32, i64 as seconds and f32, f64 as seconds, through the ToDuration trait. Dur has const constructors from_secs, from_millis, from_micros, from_nanos, from_picos, from_femtos, from_attos and from_parts, plus from_secs_f64 and neg.

Formatting in tables

Both formatters return Display values that honor width, alignment and fill, and they write without allocating:

use humanize_proper::{bin, dur};

assert_eq!(format!("{:>9}", bin(1_048_576u64)), "     1MiB");
assert_eq!(format!("{:>10}", dur(90u64)), "    01m30s");

Configuration as constants

NumFmt and DurFmt are Copy and all their builder methods are const:

use humanize_proper::{DurFmt, NumFmt, TimeUnit, Zeros};

const BYTES: NumFmt = NumFmt::bin().space(true);
const UPTIME: DurFmt = DurFmt::new().zeros(Zeros::TrimLargest).smallest(TimeUnit::Min);

Scope

Deliberately out of scope: unit prefixes below 1 such as m, µ and n, so numbers below the base print without a prefix; localization such as a decimal comma or grouped integer digits; and parsing, since this library only formats.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Authorship

This project, including its purpose and overall architecture, was conceived and designed by its human authors. The complete code was generated with AI assistance (Claude Code) under the human authors' direction.