Struct Builder

pub struct Builder { /* private fields */ }

Builder for a numeric formatter.

Implementations

impl Builder

pub fn new() -> Builder

Construct a new Builder.

pub fn build(self) -> NumFmt

Build a NumFmt instance, consuming this builder.

pub fn fill(self, param: char) -> Self

When width is greater than the actual rendered width of the number, the excess is padded with this character.

Note

Wide characters are counted according to their quantity, not their bit width.

let heart = '🖤';
assert_eq!(heart.len_utf8(), 4);
let fmt = NumFmt::builder().fill(heart).width(3).build();
let formatted = fmt.fmt(1).unwrap();
assert_eq!(formatted, "🖤🖤1");
// Note that even though we requested a width of 3, the binary length is 9.
assert_eq!(formatted.len(), 9);

pub fn align(self, param: Align) -> Self

Set the alignment of rendering within allotted width. See Align.

pub fn sign(self, param: Sign) -> Self

Set the rendering of the sign. See Sign.

pub fn hash(self, set: bool) -> Self

If a set, print a base specification before the number according to its format.

See Builder::format.

• binary: 0b
• octal: 0o
• decimal: 0d
• hex: 0x

Corresponds to the # format specifier.

pub fn zero(self, set: bool) -> Self

If set, engage the zero handler.

The zero handler overrides the padding specification to 0, and treats pad characters as part of the number, in contrast to the default behavior which treats them as arbitrary spacing.

Only valid with Align::Right and Align::Decimal.

Examples

// sign handling
assert_eq!(NumFmt::from_str("03").unwrap().fmt(-1).unwrap(),  "-01");
assert_eq!(NumFmt::from_str("0>3").unwrap().fmt(-1).unwrap(), "0-1");

// separator handling
assert_eq!(NumFmt::from_str("0>7,").unwrap().fmt(1).unwrap(), "0000001");
assert_eq!(NumFmt::from_str("07,").unwrap().fmt(1).unwrap(),  "000,001");

pub fn width(self, param: usize) -> Self

Set the width parameter.

This is a parameter for the “minimum width” that the format should take up. If the value’s string does not fill up this many characters, then the padding specified by fill/alignment will be used to take up the required space (see Builder::fill).

The width can be set dynamically:

assert_eq!(NumFmt::from_str("-^").unwrap().fmt_with(1, Dynamic::width(5)).unwrap(), "--1--");

Note: with Align::Right, this is the minimum width of the entire rendered field, not just the portion before the decimal. To set the width before the decimal, use Align::Decimal.

assert_eq!(NumFmt::from_str( "05").unwrap().fmt(1.1).unwrap(),   "001.1");
assert_eq!(NumFmt::from_str(">05").unwrap().fmt(1.1).unwrap(),   "001.1");
assert_eq!(NumFmt::from_str("v05").unwrap().fmt(1.1).unwrap(), "00001.1");

pub fn precision(self, param: Option<usize>) -> Self

Set the precision parameter.

How many digits after the decimal point are printed. Note that integers can be forced to emit decimal places with this modifier.

Precision will pad or truncate as required if set. If unset, passes through as many digits past the decimal as the underlying type naturally returns.

assert_eq!(NumFmt::from_str(".2").unwrap().fmt(3.14159).unwrap(), "3.14");
assert_eq!(NumFmt::from_str(".7").unwrap().fmt(3.14159).unwrap(), "3.1415900");

If the requested precision exceeds the native precision available to this number, the remainder is always filled with '0', even if fill is specified:

assert_eq!(NumFmt::from_str("-<6.2").unwrap().fmt(1.0_f32).unwrap(), "1.00--");

pub fn base(self, param: Base) -> Self

Set the output format.

See Base.

pub fn separator(self, param: Option<char>) -> Self

Set the separator.

A separator is a (typically non-numeric) character inserted between groups of digits to make it easier for humans to parse the number when reading. Different separators may be desirable in different contexts.

pub fn spacing(self, param: usize) -> Self

Set the spacing.

Spacing determines the number of characters in each character group. It is only of interest when the separator is set. The default spacing is 3.

pub fn decimal_separator(self, param: char) -> Self

Set the decimal separator.

This can be desirable to i.e. support German number formats, which use a . to separate numeric groups and a , as a decimal separator.

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Builder

Returns the “default value” for a type.

impl From<NumFmt> for Builder

fn from(_: NumFmt) -> Self

Converts to this type from the input type.

impl PartialEq for Builder

fn eq(&self, other: &Builder) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Builder

impl StructuralPartialEq for Builder