Expand description
Human readable formatting of numbers and durations. No dependencies, no_std, no allocation,
no unsafe.
println!("downloaded {} in {}", bin(4_823_512), dur(93));
// downloaded 4.6MiB in 01m33s§Numbers
A large number is scaled down until it fits into a few digits, and a unit prefix carries the rest of the magnitude. Which prefix system is the right one depends on what is being counted, so both are available and neither is a global setting:
- decimal (metric, factor 1000) with the prefixes
k M G T P E Z Y R Q, for disk capacities, data rates, frequencies and everything else the SI touches:dec,NumFmt::dec. - binary (factor 1024) with the prefixes
Ki Mi Gi Ti Pi Ei Zi Yi Ri Qi, for file sizes, memory and everything a computer counts in powers of two:bin,NumFmt::bin.
// A file on disk, the way `ls -lh` shows it.
println!("archive.tar.zst {}", bin(4_823_512));
// archive.tar.zst 4.6MiB
// A disk's capacity, the way the vendor prints it on the box.
println!("capacity: {}", dec(2_000_398_934_016u64));
// capacity: 2TBByte formatting is the default. bin_no_unit and dec_no_unit drop the trailing B, and
NumFmt::unit replaces it with something else:
println!("{} rows imported", dec_no_unit(18_500_000));
// 18.5M rows imported
println!("clock: {}", NumFmt::dec().unit("Hz").fmt(4_700_000_000u64));
// clock: 4.7GHzNumFmt is Copy and all of its builder methods are const, so a format used in several
places can live in a constant:
const RATE: NumFmt = NumFmt::dec().unit("B/s").space(true);
println!("throughput: {}", RATE.fmt(2_411_756));
// throughput: 2.41 MB/sValues below 1 print as a fraction of the unit, which is what a byte count wants. For measured
quantities, NumFmt::small_prefixes switches them to the SI submultiples
m µ n p f a z y r q:
const VOLT: NumFmt = NumFmt::dec().unit("V").small_prefixes(true);
println!("offset: {}", VOLT.fmt(0.0125));
// offset: 12.5mV
println!("noise floor: {}", VOLT.fmt(0.000_000_47));
// noise floor: 470nVIntegers are scaled with exact u128 arithmetic and never take a detour through f64, so
rounding rolls over into the next prefix where it should, and the extremes stay precise:
println!("{} {}", dec(999_999), bin(u64::MAX));
// 1MB 16EiBEvery primitive integer type plus f32 and f64 is accepted, through ToValue.
§Durations
The default style is 32y007d_05h01m05s: years and days, then hours, minutes and seconds, with
_ between the two groups. Leading units that are zero are dropped, so a short duration stays
short.
println!("uptime: {}", dur(3665));
// uptime: 01h01m05sZero padding keeps columns aligned, which is what a log or a table wants. In a sentence, trim it
away with Zeros, and cut the display off at the unit that carries the message with
DurFmt::smallest:
const REMAINING: DurFmt = DurFmt::new().zeros(Zeros::TrimLargest).smallest(TimeUnit::Day);
println!("certificate expires in {}", REMAINING.fmt(7_776_000));
// certificate expires in 90d
println!("took {}", DurFmt::new().zeros(Zeros::TrimAll).fmt(3665));
// took 1h1m5sFor timings, the seconds field takes a fraction, selected with Frac.
core::time::Duration is accepted directly; for anything finer than nanoseconds there is
Dur, which resolves down to attoseconds:
println!("{}", dur(Duration::from_millis(90_500)));
// 01m30s
let elapsed = Dur::from_nanos(65_123_456_789);
println!("finished in {}", DurFmt::new().frac(Frac::Millis).fmt(elapsed));
// finished in 01m05.123s
println!("one attosecond is {}", DurFmt::new().frac(Frac::Attos).fmt(Dur::from_attos(1)));
// one attosecond is 00.000000000000000001sA year is 365.2425 days, which is exactly 31_556_952 seconds, so day counts run 0..=365 and
the arithmetic stays exact at second granularity. Override it with DurFmt::secs_per_year.
§Display behavior
Both formatters return values implementing core::fmt::Display that render through
core::fmt::Formatter::pad, so width, alignment and fill work as usual and nothing is
allocated on the way:
for (name, size, age) in [("index.db", 1_048_576, 90), ("wal.log", 6_291_456, 3_600)] {
println!("{name:<10}{:>9}{:>11}", bin(size), dur(age));
}
// index.db 1MiB 01m30s
// wal.log 6MiB 01h00m00s§Scope
Deliberately out of scope: localization such as a decimal comma or grouped integer digits, and parsing, since this library only formats.
Re-exports§
pub use value::ToValue;
Structs§
- Dur
- A duration with attosecond resolution and a sign.
- DurFmt
- Configuration of the duration formatter.
- FmtDur
- A duration bound to a
DurFmt, ready to be displayed. - Num
- A number bound to a
NumFmt, ready to be displayed. - NumFmt
- Configuration of the number formatter.
Enums§
- Base
- The factor between two neighboring unit prefixes.
- Frac
- Precision of the fractional part of the seconds field.
- Prefixes
- The spelling of the binary prefixes.
- Time
Unit - The smallest unit a duration is printed down to.
- Zeros
- How leading zeros of a printed quantity are handled.
Constants§
- ATTOS_
PER_ SEC - Attoseconds per second, the resolution of
Dur.
Traits§
- ToDuration
- Types accepted by the duration formatter.
- ToValue
- Types that can be formatted by
crate::NumFmt.
Functions§
- bin
- Formats a byte count with binary prefixes, e.g.
1.5KiB. - bin_
no_ unit - Formats a number with binary prefixes and no unit, e.g.
1.5Ki. - dec
- Formats a byte count with SI prefixes, e.g.
1.5kB. - dec_
no_ unit - Formats a number with SI prefixes and no unit, e.g.
1.5k. - dur
- Formats a duration in the default style, e.g.
32y007d_05h01m05s.