Skip to main content

Crate humanize_proper

Crate humanize_proper 

Source
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: 2TB

Byte 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.7GHz

NumFmt 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/s

Values 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: 470nV

Integers 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 16EiB

Every 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: 01h01m05s

Zero 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 1h1m5s

For 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.000000000000000001s

A 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.
TimeUnit
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.