Trait SmartDisplay

trait SmartDisplay: Display

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.

Associated Types

type Metadata

User-provided metadata type.

Required Methods

fn metadata(self: &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).

# use std::fmt;
# use std::fmt::Write;
# use powerfmt::buf::WriteBuffer;
# use powerfmt::smart_display::{self, FormatterOptions, Metadata, SmartDisplay};
#[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);
# Ok::<(), Box<dyn std::error::Error>>(())

Provided Methods

fn fmt_with_metadata(self: &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.

fn fmt(self: &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.

Implementors