humanize_proper 0.1.0

Dependency-free, no_std formatting of numbers with SI/binary unit prefixes and of durations
Documentation
//! Human readable formatting of numbers and durations, without dependencies and without
//! allocation.
//!
//! # Numbers
//!
//! Numbers are formatted with unit prefixes, either binary (steps of 1024) or decimal (steps of
//! 1000). Byte formatting is the default, the `_no_unit` variants leave the `B` out.
//!
//! ```
//! use humanize_proper::{bin, dec, bin_no_unit, NumFmt, Prefixes};
//!
//! 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");
//! ```
//!
//! Integer inputs are formatted with exact integer arithmetic, including the rollover that rounding
//! can cause:
//!
//! ```
//! # use humanize_proper::dec;
//! assert_eq!(dec(999_999u64).to_string(), "1MB");
//! ```
//!
//! # Durations
//!
//! ```
//! use humanize_proper::{dur, Dur, DurFmt, Frac, 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");
//! ```
//!
//! The seconds field can carry a fraction down to attoseconds:
//!
//! ```
//! # 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");
//! ```
//!
//! # Display behavior
//!
//! Both formatters return values implementing [`core::fmt::Display`] and render through
//! [`core::fmt::Formatter::pad`], so width, alignment and fill work as usual:
//!
//! ```
//! # use humanize_proper::bin;
//! assert_eq!(format!("{:>10}", bin(1536)), "    1.5KiB");
//! ```

#![no_std]
#![forbid(unsafe_code)]
#![warn(missing_docs, missing_debug_implementations)]

mod buf;
mod duration;
mod num;
mod value;

pub use duration::{Dur, DurFmt, FmtDur, Frac, TimeUnit, ToDuration, Zeros, ATTOS_PER_SEC};
pub use num::{Base, Num, NumFmt, Prefixes};
pub use value::{ToValue, Value};

/// Formats a byte count with binary prefixes, e.g. `1.5KiB`.
///
/// ```
/// # use humanize_proper::bin;
/// assert_eq!(bin(1_048_576).to_string(), "1MiB");
/// ```
pub fn bin<V: ToValue>(value: V) -> Num {
    NumFmt::bin().fmt(value)
}

/// Formats a byte count with SI prefixes, e.g. `1.5kB`.
///
/// ```
/// # use humanize_proper::dec;
/// assert_eq!(dec(1_000_000).to_string(), "1MB");
/// ```
pub fn dec<V: ToValue>(value: V) -> Num {
    NumFmt::dec().fmt(value)
}

/// Formats a number with binary prefixes and no unit, e.g. `1.5Ki`.
///
/// ```
/// # use humanize_proper::bin_no_unit;
/// assert_eq!(bin_no_unit(1_048_576).to_string(), "1Mi");
/// ```
pub fn bin_no_unit<V: ToValue>(value: V) -> Num {
    NumFmt::bin().no_unit().fmt(value)
}

/// Formats a number with SI prefixes and no unit, e.g. `1.5k`.
///
/// ```
/// # use humanize_proper::dec_no_unit;
/// assert_eq!(dec_no_unit(1_000_000).to_string(), "1M");
/// ```
pub fn dec_no_unit<V: ToValue>(value: V) -> Num {
    NumFmt::dec().no_unit().fmt(value)
}

/// Formats a duration in the default style, e.g. `32y007d_05h01m05s`.
///
/// ```
/// # use humanize_proper::dur;
/// assert_eq!(dur(90).to_string(), "01m30s");
/// ```
pub fn dur<D: ToDuration>(duration: D) -> FmtDur {
    DurFmt::new().fmt(duration)
}