prettier_bytes/

lib.rs

#![doc = include_str!("../README.md")]
#![no_std]
#![deny(clippy::pedantic)]
#![deny(clippy::nursery)]
#![forbid(clippy::indexing_slicing)]
#![forbid(clippy::panic)]
#![forbid(clippy::unwrap_used)]
#![forbid(clippy::expect_used)]
#![forbid(clippy::unreachable)]
#![forbid(clippy::todo)]
#![forbid(clippy::unimplemented)]
#![forbid(clippy::alloc_instead_of_core)]
#![forbid(clippy::float_arithmetic)]
#![forbid(clippy::cast_possible_wrap)]
#![forbid(clippy::cast_possible_truncation)]
#![forbid(unsafe_code)]

use core::fmt;

/// A configurable formatter for byte sizes.
///
/// # Examples
///
/// ```
/// use prettier_bytes::{ByteFormatter, Standard};
///
/// let fmt = ByteFormatter::new().standard(Standard::SI);
/// assert_eq!(fmt.format(2500).as_str().unwrap(), "2.50 kB");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ByteFormatter {
    unit: Unit,
    standard: Standard,
    space: bool,
}

impl Default for ByteFormatter {
    fn default() -> Self {
        Self::new()
    }
}

impl ByteFormatter {
    /// Creates a new `ByteFormatter` with sensible defaults:
    /// Binary standard (Base 1024), Bytes, and a space between the number and unit.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            unit: Unit::Bytes,
            standard: Standard::Binary,
            space: true,
        }
    }

    /// Sets the formatting standard (e.g., SI vs Binary).
    #[must_use]
    pub const fn standard(mut self, standard: Standard) -> Self {
        self.standard = standard;
        self
    }

    /// Sets the base unit (e.g., Bytes vs Bits).
    #[must_use]
    pub const fn unit(mut self, unit: Unit) -> Self {
        self.unit = unit;
        self
    }

    /// Determines whether a space is placed between the number and the unit.
    ///
    /// Defaults to `true` (e.g., `"1.50 MB"`). If set to `false`, the space is omitted
    /// (e.g., `"1.50MB"`).
    ///
    /// # Examples
    ///
    /// ```
    /// use prettier_bytes::ByteFormatter;
    ///
    /// let fmt_spaced = ByteFormatter::new().space(true);
    /// assert_eq!(fmt_spaced.format(1024).as_str().unwrap(), "1.00 KiB");
    ///
    /// let fmt_compact = ByteFormatter::new().space(false);
    /// assert_eq!(fmt_compact.format(1024).as_str().unwrap(), "1.00KiB");
    /// ```
    #[must_use]
    pub const fn space(mut self, space: bool) -> Self {
        self.space = space;
        self
    }

    /// Formats the given value and returns a stack-allocated buffer.
    #[must_use]
    pub fn format(self, val: u64) -> FormattedBytes {
        FormattedBytes::from_formatter(val, self.unit, self.standard, self.space)
    }
}

/// Represents the base unit to format against.
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
pub enum Unit {
    /// Formats with a trailing 'B' (e.g., MB, GiB).
    Bytes,
    /// Formats with a trailing 'b' (e.g., Mb, Mib, Gib).
    Bits,
}

/// Represents the mathematical standard for calculating magnitudes.
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
pub enum Standard {
    /// Base 1000 (SI standard). Produces kB, MB, GB, etc.
    SI,
    /// Base 1024 (IEC/Binary standard). Produces KiB, MiB, GiB, etc.
    Binary,
}

/// A stack-allocated buffer containing the formatted byte string.
///
/// `FormattedBytes` calculates the formatting upon instantiation and stores
/// the result internally. It can be cheaply converted to a `&str` or `&[u8]`.
#[derive(Clone, Copy)]
pub struct FormattedBytes {
    buf: [u8; 16],
    len: usize,
}

impl FormattedBytes {
    pub(crate) fn from_formatter(val: u64, unit: Unit, standard: Standard, space: bool) -> Self {
        // Determine the magnitude (0=Base, 1=Kilo, 2=Mega, etc.)
        let mag = if val == 0 {
            0
        } else {
            match standard {
                Standard::SI => (val.ilog10() / 3) as usize,
                Standard::Binary => (val.ilog2() / 10) as usize,
            }
        };

        // Cap magnitude at 6 (Exabytes), the physical limit of a u64.
        let mag = mag.min(6);

        // We calculate both the whole number AND the fraction simultaneously
        // such that LLVM never emits a dynamic CPU `div` instruction.
        let (mut whole, mut frac) = if mag == 0 {
            (val, 0)
        } else {
            match standard {
                Standard::Binary => {
                    // Base 1024: Pure bitwise operations (1 clock cycle)
                    let shift = mag * 10;
                    let divisor = 1_u64 << shift;
                    let whole = val >> shift;
                    let rem = val & (divisor - 1);

                    // To prevent u64 overflow on Exbibytes (mag 6), we shift down by 7.
                    let (scaled_rem, final_shift) = if mag == 6 {
                        (rem >> 7, shift - 7)
                    } else {
                        (rem, shift)
                    };

                    // Rounding: Add half of the divisor before shifting to round to nearest integer
                    let rounder = 1_u64 << (final_shift - 1);
                    let f = ((scaled_rem * 100) + rounder) >> final_shift;

                    (whole, f)
                }
                Standard::SI => {
                    // Base 1000: We use a local macro to force LLVM to calculate the
                    // fraction while the divisor is a hardcoded literal
                    // This triggers reciprocal multiplication, bypassing CPU division
                    macro_rules! calc_si {
                        ($div:expr) => {{
                            let w = val / $div;
                            let r = val % $div;
                            let (sr, sd) = if mag == 6 {
                                (r >> 7, $div >> 7)
                            } else {
                                (r, $div)
                            };
                            let f = (sr * 100 + (sd / 2)) / sd;
                            (w, f)
                        }};
                    }

                    match mag {
                        1 => calc_si!(1_000_u64),
                        2 => calc_si!(1_000_000_u64),
                        3 => calc_si!(1_000_000_000_u64),
                        4 => calc_si!(1_000_000_000_000_u64),
                        5 => calc_si!(1_000_000_000_000_000_u64),
                        _ => calc_si!(1_000_000_000_000_000_000_u64),
                    }
                }
            }
        };

        // Carry over if rounding pushed the fraction to 100
        if frac >= 100 {
            frac = 0;
            whole += 1;
        }

        // String assembly
        let mut buf = [0u8; 16];
        let mut iter = buf.iter_mut();

        // Safe iterator pushing
        let mut push = |b: u8| {
            if let Some(slot) = iter.next() {
                *slot = b;
            }
        };

        let (num_buf, num_len) = format_small_num(whole);

        // Push whole number
        for b in num_buf.into_iter().take(num_len) {
            push(b);
        }

        // Push decimals
        if mag != 0 {
            push(b'.');
            push(b'0' + u8::try_from(frac / 10).unwrap_or(0));
            push(b'0' + u8::try_from(frac % 10).unwrap_or(0));
        }

        // Push space
        if space {
            push(b' ');
        }

        // Push prefixes
        if mag != 0 {
            let prefix = match (mag, standard) {
                (1, Standard::SI) => b'k',
                (1, Standard::Binary) => b'K',
                (2, _) => b'M',
                (3, _) => b'G',
                (4, _) => b'T',
                (5, _) => b'P',
                _ => b'E',
            };
            push(prefix);

            if standard == Standard::Binary {
                push(b'i');
            }
        }

        // Push unit
        push(match unit {
            Unit::Bytes => b'B',
            Unit::Bits => b'b',
        });

        // Calculate final length mathematically
        let len = 16 - iter.len();

        Self { buf, len }
    }

    /// Returns the formatted output as a raw byte slice.
    /// Useful for direct `std::io::Write` usage.
    #[inline]
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        self.buf.get(..self.len).unwrap_or(&self.buf)
    }

    /// Returns the formatted output as a UTF-8 string slice.
    ///
    /// # Errors
    ///
    /// Returns a `core::str::Utf8Error` if the internal buffer contains
    /// invalid UTF-8 bytes. (Note: The format method only writes valid
    /// ASCII characters, so this is guaranteed to succeed in practice).
    #[inline]
    pub fn as_str(&self) -> Result<&str, core::str::Utf8Error> {
        let bytes = self.buf.get(..self.len).unwrap_or(&self.buf);
        core::str::from_utf8(bytes)
    }
}

/// Allows `FormattedBytes` to be used in standard Rust formatting macros
/// (e.g., `format!()`, `println!()`, `write!()`).
impl fmt::Display for FormattedBytes {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str().map_err(|_| fmt::Error)?)
    }
}

/// Inlines formatting for numbers strictly < 1024.
///
/// Avoids the heavy loop/modulo cost of general `itoa` routines.
#[inline]
fn format_small_num(n: u64) -> ([u8; 4], usize) {
    if n < 10 {
        ([b'0' + u8::try_from(n).unwrap_or(0), 0, 0, 0], 1)
    } else if n < 100 {
        (
            [
                b'0' + u8::try_from(n / 10).unwrap_or(0),
                b'0' + u8::try_from(n % 10).unwrap_or(0),
                0,
                0,
            ],
            2,
        )
    } else if n < 1000 {
        (
            [
                b'0' + u8::try_from(n / 100).unwrap_or(0),
                b'0' + u8::try_from((n / 10) % 10).unwrap_or(0),
                b'0' + u8::try_from(n % 10).unwrap_or(0),
                0,
            ],
            3,
        )
    } else {
        (
            [
                b'0' + u8::try_from(n / 1000).unwrap_or(0),
                b'0' + u8::try_from((n / 100) % 10).unwrap_or(0),
                b'0' + u8::try_from((n / 10) % 10).unwrap_or(0),
                b'0' + u8::try_from(n % 10).unwrap_or(0),
            ],
            4,
        )
    }
}

#[cfg(test)]
mod tests {
    extern crate alloc;

    use alloc::format;

    use super::*;

    macro_rules! assert_fmt {
        ($val:expr, $unit:path, $std:path, $space:expr, $expected:expr) => {
            let fmt = ByteFormatter::new()
                .unit($unit)
                .standard($std)
                .space($space)
                .format($val);
            assert_eq!(fmt.as_str().unwrap(), $expected);
        };
    }

    #[test]
    fn test_zero() {
        assert_fmt!(0, Unit::Bytes, Standard::SI, true, "0 B");
        assert_fmt!(0, Unit::Bits, Standard::SI, true, "0 b");
        assert_fmt!(0, Unit::Bytes, Standard::Binary, false, "0B");
        assert_fmt!(0, Unit::Bits, Standard::Binary, false, "0b");
    }

    #[test]
    fn test_base_units_under_1000() {
        // Values < 1000 should format as raw bytes with no decimals in either standard.
        assert_fmt!(1, Unit::Bytes, Standard::SI, true, "1 B");
        assert_fmt!(12, Unit::Bytes, Standard::Binary, true, "12 B");
        assert_fmt!(345, Unit::Bytes, Standard::SI, false, "345B");
        assert_fmt!(999, Unit::Bytes, Standard::SI, true, "999 B");
        assert_fmt!(999, Unit::Bytes, Standard::Binary, true, "999 B");
    }

    #[test]
    fn test_si_exact_magnitudes() {
        // Tests exactly hitting the boundary of SI prefixes (Base 1000)
        assert_fmt!(1_000, Unit::Bytes, Standard::SI, true, "1.00 kB");
        assert_fmt!(1_000_000, Unit::Bytes, Standard::SI, true, "1.00 MB");
        assert_fmt!(1_000_000_000, Unit::Bytes, Standard::SI, true, "1.00 GB");
        assert_fmt!(
            1_000_000_000_000,
            Unit::Bytes,
            Standard::SI,
            true,
            "1.00 TB"
        );
        assert_fmt!(
            1_000_000_000_000_000,
            Unit::Bytes,
            Standard::SI,
            true,
            "1.00 PB"
        );
        assert_fmt!(
            1_000_000_000_000_000_000,
            Unit::Bytes,
            Standard::SI,
            true,
            "1.00 EB"
        );
    }

    #[test]
    fn test_binary_exact_magnitudes() {
        // Tests exactly hitting the boundary of Binary prefixes (Base 1024)
        assert_fmt!(1_024, Unit::Bytes, Standard::Binary, true, "1.00 KiB");
        assert_fmt!(1_048_576, Unit::Bytes, Standard::Binary, true, "1.00 MiB");
        assert_fmt!(
            1_073_741_824,
            Unit::Bytes,
            Standard::Binary,
            true,
            "1.00 GiB"
        );
        assert_fmt!(
            1_099_511_627_776,
            Unit::Bytes,
            Standard::Binary,
            true,
            "1.00 TiB"
        );
        assert_fmt!(
            1_125_899_906_842_624,
            Unit::Bytes,
            Standard::Binary,
            true,
            "1.00 PiB"
        );
        assert_fmt!(
            1_152_921_504_606_846_976,
            Unit::Bytes,
            Standard::Binary,
            true,
            "1.00 EiB"
        );
    }

    #[test]
    fn test_si_vs_binary_difference() {
        // 1,000 bytes is 1.00 kB in SI, but still 1000 B in Binary (since it's < 1024)
        assert_fmt!(1_000, Unit::Bytes, Standard::SI, true, "1.00 kB");
        assert_fmt!(1_000, Unit::Bytes, Standard::Binary, true, "1000 B");

        // 1,023 bytes
        assert_fmt!(1_023, Unit::Bytes, Standard::SI, true, "1.02 kB");
        assert_fmt!(1_023, Unit::Bytes, Standard::Binary, true, "1023 B");
    }

    #[test]
    fn test_rounding_and_decimals() {
        // 1,500 bytes = 1.50 kB
        assert_fmt!(1_500, Unit::Bytes, Standard::SI, true, "1.50 kB");

        // 1,536 bytes = 1.50 KiB (1024 + 512)
        assert_fmt!(1_536, Unit::Bytes, Standard::Binary, true, "1.50 KiB");

        // Rounding down: 1,004 bytes -> 1.00 kB
        assert_fmt!(1_004, Unit::Bytes, Standard::SI, true, "1.00 kB");

        // Rounding up: 1,005 bytes -> 1.01 kB
        assert_fmt!(1_005, Unit::Bytes, Standard::SI, true, "1.01 kB");

        // 1.23 MB
        assert_fmt!(1_230_000, Unit::Bytes, Standard::SI, true, "1.23 MB");
    }

    #[test]
    fn test_carry_over_rounding() {
        // If a value is right on the edge of the next decimal, it should round the whole number up.
        // 999,999 bytes in SI is 999.999 kB. Rounding to 2 digits makes it 1000.00 kB.
        assert_fmt!(999_999, Unit::Bytes, Standard::SI, true, "1000.00 kB");

        // Binary equivalent: 1,048,575 bytes is 1 byte shy of 1 MiB.
        // In KiB, it's 1023.999... which rounds up to 1024.00 KiB.
        assert_fmt!(
            1_048_575,
            Unit::Bytes,
            Standard::Binary,
            true,
            "1024.00 KiB"
        );
    }

    #[test]
    fn test_formatting_variations() {
        let val = 2_500_000;

        // Bytes vs Bits
        assert_fmt!(val, Unit::Bytes, Standard::SI, true, "2.50 MB");
        assert_fmt!(val, Unit::Bits, Standard::SI, true, "2.50 Mb");

        // SI vs Binary
        assert_fmt!(val, Unit::Bytes, Standard::SI, true, "2.50 MB");
        assert_fmt!(val, Unit::Bytes, Standard::Binary, true, "2.38 MiB");

        // Spacing vs No Spacing
        assert_fmt!(val, Unit::Bytes, Standard::SI, true, "2.50 MB");
        assert_fmt!(val, Unit::Bytes, Standard::SI, false, "2.50MB");
    }

    #[test]
    fn test_extreme_values() {
        // u64::MAX is 18_446_744_073_709_551_615

        // In SI (Base 1000): ~18.45 Exabytes
        assert_fmt!(u64::MAX, Unit::Bytes, Standard::SI, true, "18.45 EB");

        // In Binary (Base 1024):
        // u64::MAX is just 1 byte shy of 16 Exbibytes (16.00 EiB after rounding)
        assert_fmt!(u64::MAX, Unit::Bytes, Standard::Binary, true, "16.00 EiB");
    }

    #[test]
    fn test_as_bytes() {
        // Ensure the raw byte slice matches the string representation exactly
        let fmt = ByteFormatter::new()
            .unit(Unit::Bytes)
            .standard(Standard::SI)
            .space(false)
            .format(1500);
        assert_eq!(fmt.as_bytes(), b"1.50kB");
    }

    #[test]
    fn test_number_boundaries() {
        // Tests the transition points inside the `format_small_num` logic
        assert_fmt!(9, Unit::Bytes, Standard::SI, true, "9 B"); // 1 digit max
        assert_fmt!(10, Unit::Bytes, Standard::SI, true, "10 B"); // 2 digits min
        assert_fmt!(99, Unit::Bytes, Standard::SI, true, "99 B"); // 2 digits max
        assert_fmt!(100, Unit::Bytes, Standard::SI, true, "100 B"); // 3 digits min
        assert_fmt!(999, Unit::Bytes, Standard::SI, true, "999 B"); // 3 digits max
    }

    #[test]
    fn test_display_trait() {
        let fmt = ByteFormatter::new()
            .unit(Unit::Bytes)
            .standard(Standard::Binary)
            .space(true)
            .format(1_048_576);

        // This implicitly calls the `Display` trait implementation!
        let output = format!("{fmt}");

        assert_eq!(output, "1.00 MiB");
    }
}