Crate num_runtime_fmt[−][src]
Format numbers according to a runtime specification.
Entry Points
The core of this crate is the NumFmt
type. You can build it explicitly,
or parse it from a format string with similar grammar to that of the
standard library.
Given an instance of NumFmt
, you can call its fmt
method to simply format
a number, or its fmt_with
method to apply dynamic parameters.
Format String Grammar
The gramar for the format string derives substantially from the standard library’s:
format_spec := [[fill]align][sign]['#'][['0']width]['.' precision][format][separator[spacing]]
fill := character
align := '<' | '^' | '>' | 'v'
sign := '+' | '-'
width := integer not beginning with '0'
precision := integer
format := 'b' | 'o' | 'd' | 'x' | 'X'
separator := '_', | ',' | ' '
spacing := integer
Note
There is no special syntax for dynamic insertion of with
, precision
and spacing
.
Simply use NumFmt::fmt_with
; the dynamic values provided there always override any
values for those fields, whether set or not in the format string.
fill
Any single char
which precedes an align specifier is construed as the fill
character: 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);
align
ment
>
: the output is right-aligned inwidth
columns (default).^
: the output is centered inwidth
columns.<
: the output is left-aligned inwidth
columns.v
: attempt to align the decimal point at column indexwidth
. For integers, equivalent to>
.
sign
-
: print a leading-
for negative numbers, and nothing in particular for positive (default)+
: print a leading+
for positive numbers
#
If a #
character is present, print a base specification before the number
according to its format (see format
below).
- binary:
0b
- octal:
0o
- decimal:
0d
- hex:
0x
This base specification counts toward the width of the number:
assert_eq!(NumFmt::from_str("#04b").unwrap().fmt(2).unwrap(), "0b10");
0
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.
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");
width
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
fill
above).
When using the $
sigil instead of an explicit width, the width can be set
dynamically:
assert_eq!(NumFmt::from_str("-^").unwrap().fmt_with(1, Dynamic::width(5)).unwrap(), "--1--");
If an explicit width is not provided, defaults to 0.
precision
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--");
format
b
: Emit this number’s binary representationo
: Emit this number’s octal representationd
: Emit this number’s decimal representation (default)x
: Emit this number’s hexadecimal representation with lowercase lettersX
: Emit this number’s hexadecimal representation with uppercase letters
Note
This is one of a few areas where the standard library has capabilities this library does not: it supports some other numeric formats. Pull requests welcomed to bring this up to parity.
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.
_
: Separate numeric groups with an underscore,
: Separate numeric groups with a comma
By default, numeric groups are not separated. It is not possible to explicitly specify that numeric groups are not separated when using a format string. However, this can be specified when building the formatter via builder.
When using the builder to explicitly set formatter options, it is also possible
to separate numeric groups with an arbitrary char
. This can be desirable to
i.e. support German number formats, which use a .
to separate numeric groups
and a ,
as a decimal separator.
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.
Re-exports
pub use numeric_trait::Numeric; |
Modules
numeric_trait | |
parse |
Structs
Builder | Builder for a numeric formatter. |
Dynamic | Container for setting certain parameters dynamically. |
NumFmt | Formatter for numbers. |
Enums
Align | Positioning of rendered number within the allotted |
Base | The base / format with which to represent this number. |
Error | |
Sign | Whether to render a sign sigil. |