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 ;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
Integers are formatted with exact u128 arithmetic, so rounding rolls over correctly and even
u128 inputs stay precise:
use ;
assert_eq!;
assert_eq!;
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_digitsnever shortens it: at 1 significant digit,999still prints as999B. - Values below 1 carry
sig_digits - 1fraction digits, e.g.0.125 -> "0.13B". Leading zeros of the fraction are not counted as significant. NaNprints asNaN, infinities asinfand-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 ;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
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 ;
let d = from_nanos;
assert_eq!;
assert_eq!;
assert_eq!;
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_952seconds, so day counts run0..=365and 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, soDur::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 ;
assert_eq!;
assert_eq!;
Configuration as constants
NumFmt and DurFmt are Copy and all their builder methods are const:
use ;
const BYTES: NumFmt = bin.space;
const UPTIME: DurFmt = new.zeros.smallest;
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
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
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.