pub trait SmartDisplay: Display {
type Metadata;
// Required method
fn metadata(&self, f: FormatterOptions) -> Metadata<'_, Self>;
// Provided methods
fn fmt_with_metadata(
&self,
f: &mut Formatter<'_>,
_metadata: Metadata<'_, Self>,
) -> Result { ... }
fn fmt(&self, f: &mut Formatter<'_>) -> Result { ... }
}Expand description
Format trait that allows authors to provide additional information.
This trait is similar to Display, but allows the author to provide additional information
to the formatter. This information is provided in the form of a custom metadata type.
The only required piece of metadata is the width of the value. This is before it is passed to the formatter (i.e. it does not include any padding added by the formatter). Other information can be stored in a custom metadata type as needed. This information may be made available to downstream users, but it is not required.
Note: While both fmt_with_metadata and fmt have default implementations, it is strongly
recommended to implement only fmt_with_metadata. fmt should be implemented if and only if
the type does not require any of the calculated metadata. In that situation, fmt_with_metadata
should be omitted.
Required Associated Types§
Required Methods§
sourcefn metadata(&self, f: FormatterOptions) -> Metadata<'_, Self>
fn metadata(&self, f: FormatterOptions) -> Metadata<'_, Self>
Compute any information needed to format the value. This must, at a minimum, determine the width of the value before any padding is added by the formatter.
If the type uses other types that implement SmartDisplay verbatim, the inner types should
have their metadata calculated and included in the returned value.
§Lifetimes
This method’s return type contains a lifetime to self. This ensures that the metadata will
neither outlive the value nor be invalidated by a mutation of the value (barring interior
mutability).
#[derive(Debug)]
struct WrappedBuffer(WriteBuffer<128>);
#[smart_display::delegate]
impl SmartDisplay for WrappedBuffer {
type Metadata = ();
fn metadata(&self, _: FormatterOptions) -> Metadata<'_, Self> {
Metadata::new(self.0.len(), self, ())
}
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.pad(self.0.as_str())
}
}
let mut buf = WrappedBuffer(WriteBuffer::new());
let metadata = buf.metadata(FormatterOptions::default());
// We cannot mutate the buffer while it is borrowed and use its previous metadata on the
// following line.
write!(buf.0, "Hello, world!")?;
assert_eq!(metadata.width(), 13);Provided Methods§
sourcefn fmt_with_metadata(
&self,
f: &mut Formatter<'_>,
_metadata: Metadata<'_, Self>,
) -> Result
fn fmt_with_metadata( &self, f: &mut Formatter<'_>, _metadata: Metadata<'_, Self>, ) -> Result
Format the value using the given formatter and metadata. The formatted output should have the width indicated by the metadata. This is before any padding is added by the formatter.
If the metadata is not needed, you should implement the fmt method instead.
sourcefn fmt(&self, f: &mut Formatter<'_>) -> Result
fn fmt(&self, f: &mut Formatter<'_>) -> Result
Format the value using the given formatter. This is the same as Display::fmt.
The default implementation of this method calls fmt_with_metadata with the result of
metadata. Generally speaking, this method should not be implemented. You should implement
the fmt_with_metadata method instead.