num_runtime_fmt/numeric_trait/
mod.rs

1pub mod impls;
2
3/// This trait enables a type to be formatted by [`NumFmt`][crate::NumFmt].
4///
5/// The fundamental abstraction used is an optional iterator over a stream of characters. Returning
6/// `None` always indicates that representation in that base is not available for this type. Any
7/// particular function implemented for a type should always return either `None` or `Some`; it
8/// should not depend on the value being formatted.
9///
10/// In all cases, when implemented, the iterators must iterate away from the decimal: for a
11/// representation of `N` in base `B`, it must return the appropriate digit for `B**0`, `B**1`, ...
12/// `BN**k` where `k` is `ceil(log_B(N))`.
13///
14/// Iterators should only return digits within the appropriate range for the base. All other
15/// formatting is handled by the formatter.
16///
17/// Iterator types must be declared even when the appropriate function always returns `None`. In
18/// those cases, [`std::iter::Empty`] is appropriate.
19pub trait Numeric {
20    /// Iterate over binary digits of this number.
21    ///
22    /// Legal output characters: `[01]`.
23    type BinIter: Iterator<Item = char>;
24
25    /// Iterate over octal digits of this number.
26    ///
27    /// Legal output characters: `[0-7]`.
28    type OctIter: Iterator<Item = char>;
29
30    /// Iterate over decimal digits of this number which are >= 1.
31    ///
32    /// Legal output characters: `[0-9]`.
33    type DecLeftIter: Iterator<Item = char>;
34
35    /// Iterate over decimal digits of this number which are < 1.
36    ///
37    /// Legal output characters: `[0-9]`.
38    ///
39    /// This should iterate away from the decimal: for a representation of `N`, it must return the appropriate
40    /// digit for `10**-1`, `10**-2`, etc.
41    type DecRightIter: Iterator<Item = char>;
42
43    /// Iterate over hexadecimal digits of this number, with letters as lowercase.
44    ///
45    /// Legal output characters: `[0-9a-f]`.
46    type HexIter: Iterator<Item = char>;
47
48    /// Iterate over the binary digits of this number, from least to most significant.
49    ///
50    /// This function should always return either `None` or `Some`; it should not depend on the
51    /// value of `self`.
52    fn binary(&self) -> Option<Self::BinIter>;
53
54    /// Iterate over the octal digits of this number, from least to most significant.
55    ///
56    /// This function should always return either `None` or `Some`; it should not depend on the
57    /// value of `self`.
58    fn octal(&self) -> Option<Self::OctIter>;
59
60    /// Produce a pair of iterators over the decimal digits of this number.
61    ///
62    /// ## `DecLeftIter`
63    ///
64    /// `Self::DecLeftIter` must iterate over the decimal digits of this number which are >= 1, from
65    /// least to most significant. Note that it is assumed that all numeric types can produce a
66    /// decimal representation of an integer component.
67    ///
68    /// ## `DecRightIter`
69    ///
70    /// `Self::DecRightIter` should iterate away from the decimal: for a representation of `N`, it
71    /// must return the appropriate digit for `10**-1`, `10**-2`, etc.
72    ///
73    /// It is an exception to the general rule; it may return `None` or `Some` according to the
74    /// value of `self`.
75    ///
76    /// If `Self` is not an integral type, such as `f64`, but `self` is an integer, like `1.0`, then
77    /// the output will vary by what this function returns as follows:
78    ///
79    /// - `None` => `"1"`
80    /// - `Some(std::iter::empty())` => `"1."`
81    /// - `Some(std::iter::once('0')) => `"1.0"`
82    fn decimal(&self) -> (Self::DecLeftIter, Option<Self::DecRightIter>);
83
84    /// Iterate over the hexadecimal digits of this number, with letters as lowercase.
85    ///
86    /// This function should always return either `None` or `Some`; it should not depend on the
87    /// value of `self`.
88    ///
89    /// Note that the implementation must provide only the lowercase implementation. The formatter
90    /// uppercases the output of this function when the user requests uppercase hexadecimal.
91    fn hex(&self) -> Option<Self::HexIter>;
92
93    /// `true` when this value is less than 0.
94    fn is_negative(&self) -> bool;
95}
num_runtime_fmt/numeric_trait/mod.rs

num_runtime_fmt/numeric_trait/
mod.rs
