Macro format_value

macro_rules! format_value {
    ($name:ident, $fmt_str:literal) => { ... };
    ($name:ident, $fmt_str:literal, groupings: $separator:expr) => { ... };
    ($name:ident, $fmt_str:literal, groupings: $separator:expr, no_unit) => { ... };
}

Formats a Value’s mantissa and unit prefix (but not the unit itself). Because it simply delegates to format_args!(), the output should be consumed by macros such as println!(), write!(), etc.

It provides more control than the Display implementation in Value because you can provide the number formatting.

Example

use si_scale::{value::Value, format_value};

let x = 3.4e-12f32;
let v: Value = x.into();
let unit = "F"; // just something displayable.

let actual = format!("result is {}{u}",
    format_value!(v, "{:>8.2}"), u = unit
);
let expected = "result is     3.40 pF";
assert_eq!(actual, expected);

// left alignment

let actual = format!("result is {}{u}",
    format_value!(v, "{:<8.3}"), u = unit
);
let expected = "result is 3.400    pF";
assert_eq!(actual, expected);

Additionally, you can provide a symbol for thousands’ groupings.

Example

In this example, the number x is converted into a value and displayed using the most appropriate SI prefix. The user chose to constrain the prefix to be anything lower than Unit (1) because kilo-seconds make no sense.

use si_scale::format_value;
use si_scale::{value::Value, base::Base, prefix::Constraint};

let x = 1234.5678;
let v = Value::new_with(x, Base::B1000, Constraint::UnitAndBelow);
let unit = "s";

let actual = format!(
    "result is {}{u}",
    format_value!(v, "{:.5}", groupings: '_'),
    u = unit
);
let expected = "result is 1_234.567_80 s";
assert_eq!(actual, expected);