powerfmt/

smart_display.rs

//! Definition of [`SmartDisplay`] and its related items.
//!
//! [`SmartDisplay`] is a trait that allows authors to provide additional information to both the
//! formatter and other users. This information is provided in the form of a 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.
//!
//! This module contains the [`SmartDisplay`] and associated items.
//!
//! # Example
//!
//! ```rust
//! use std::fmt;
//!
//! use powerfmt::ext::FormatterExt as _;
//! use powerfmt::smart_display::{self, FormatterOptions, Metadata, SmartDisplay};
//!
//! #[derive(Debug)]
//! struct User {
//!     id: usize,
//! }
//!
//! // If you try to use `UserMetadata` in the `SmartDisplay` implementation, you will get a
//! // compiler error about a private type being used publicly. To avoid this, use this attribute to
//! // declare a private metadata type. You shouldn't need to worry about how this works, but be
//! // aware that any public fields or methods remain usable by downstream users.
//! #[smart_display::private_metadata]
//! struct UserMetadata {
//!     username: String,
//!     legal_name: String,
//! }
//!
//! // This attribute can be applied to `SmartDisplay` implementations. It will generate an
//! // implementation of `Display` that delegates to `SmartDisplay`, avoiding the need to write
//! // boilerplate.
//! #[smart_display::delegate]
//! impl SmartDisplay for User {
//!     type Metadata = UserMetadata;
//!
//!     fn metadata(&self, _: FormatterOptions) -> Metadata<'_, Self> {
//!         // This could be obtained from a database, for example.
//!         let legal_name = "John Doe".to_owned();
//!         let username = "jdoe".to_owned();
//!
//!         // Note that this must be kept in sync with the implementation of `fmt_with_metadata`.
//!         let width = smart_display::padded_width_of!(username, " (", legal_name, ")",);
//!
//!         Metadata::new(
//!             width,
//!             self,
//!             UserMetadata {
//!                 username,
//!                 legal_name,
//!             },
//!         )
//!     }
//!
//!     // Use the now-generated metadata to format the value. Here we use the `pad_with_width`
//!     // method to use the alignment and desired width from the formatter.
//!     fn fmt_with_metadata(
//!         &self,
//!         f: &mut fmt::Formatter<'_>,
//!         metadata: Metadata<Self>,
//!     ) -> fmt::Result {
//!         f.pad_with_width(
//!             metadata.unpadded_width(),
//!             format_args!("{} ({})", metadata.username, metadata.legal_name),
//!         )
//!     }
//! }
//!
//! let user = User { id: 42 };
//! assert_eq!(user.to_string(), "jdoe (John Doe)");
//! assert_eq!(format!("{user:>20}"), "     jdoe (John Doe)");
//! ```

use core::cmp;
use core::convert::Infallible;
use core::fmt::{Alignment, Debug, Display, Formatter, Result};
use core::marker::PhantomData;
use core::mem::MaybeUninit;
use core::ops::Deref;

/// Compute the width of multiple items while optionally declaring the options for each item.
///
/// ```rust
/// # use powerfmt::smart_display;
/// let alpha = 0;
/// let beta = 1;
/// let gamma = 100;
///
/// let width = smart_display::padded_width_of!(
///     alpha, // use the default options
///     beta => width(2), // use the specified options
///     gamma => width(2) sign_plus(true), // use multiple options
/// );
/// assert_eq!(width, 7);
///
/// let formatted = format!("{alpha}{beta:2}{gamma:+2}");
/// assert_eq!(formatted.len(), width);
/// ```
///
/// Supported options are:
///
/// Option                      | Method called
/// ---                         | ---
/// `fill(char)`                | [`FormatterOptions::with_fill`]
/// `sign_plus(bool)`           | [`FormatterOptions::with_sign_plus`]
/// `sign_minus(bool)`          | [`FormatterOptions::with_sign_minus`]
/// `align(Alignment)`          | [`FormatterOptions::with_align`]
/// `width(usize)`              | [`FormatterOptions::with_width`]
/// `precision(usize)`          | [`FormatterOptions::with_precision`]
/// `alternate(bool)`           | [`FormatterOptions::with_alternate`]
/// `sign_aware_zero_pad(bool)` | [`FormatterOptions::with_sign_aware_zero_pad`]
///
/// If there are future additions to [`FormatterOptions`], they will be added to this macro as well.
///
/// Options may be provided in any order and will be called in the order they are provided. The
/// ordering matters if providing both `sign_plus` and `sign_minus`.
#[cfg(doc)]
#[doc(hidden)] // Don't show at crate root.
#[macro_export]
macro_rules! padded_width_of {
    ($($t:tt)*) => {};
}

#[cfg(not(doc))]
#[allow(missing_docs)] // This is done with `#[cfg(doc)]` to avoid showing the various rules.
#[macro_export]
macro_rules! __not_public_at_root__padded_width_of {
    // Base case
    (@inner [] [$($output:tt)+]) => { $($output)+ };
    (@inner [$e:expr $(, $($remaining:tt)*)?] [$($expansion:tt)+]) => {
        $crate::smart_display::padded_width_of!(@inner [$($($remaining)*)?] [
            $($expansion)+ + $crate::smart_display::Metadata::padded_width_of(
                &$e,
                $crate::smart_display::padded_width_of!(@options)
            )
        ])
    };
    (@inner
        [$e:expr => $($call:ident($call_expr:expr))+ $(, $($remaining:tt)*)?]
        [$($expansion:tt)+]
    ) => {
        $crate::smart_display::padded_width_of!(@inner [$($($remaining)*)?] [
            $($expansion)+ + $crate::smart_display::Metadata::padded_width_of(
                &$e,
                *$crate::smart_display::padded_width_of!(@options $($call($call_expr))+)
            )
        ])
    };

    // Options base case
    (@options_inner [] [$($output:tt)+]) => { $($output)+ };
    (@options_inner [fill($e:expr) $($remaining:tt)*] [$($expansion:tt)*]) => {
        $crate::smart_display::padded_width_of!(@options_inner [$($remaining)*] [
            $($expansion)*.with_fill($e)
        ])
    };
    (@options_inner [sign_plus($e:expr) $($remaining:tt)*] [$($expansion:tt)*]) => {
        $crate::smart_display::padded_width_of!(@options_inner [$($remaining)*] [
            $($expansion)*.with_sign_plus($e)
        ])
    };
    (@options_inner [sign_minus($e:expr) $($remaining:tt)*] [$($expansion:tt)*]) => {
        $crate::smart_display::padded_width_of!(@options_inner [$($remaining)*] [
            $($expansion)*.with_sign_minus($e)
        ])
    };
    (@options_inner [align($e:expr) $($remaining:tt)*] [$($expansion:tt)*]) => {
        $crate::smart_display::padded_width_of!(@options_inner [$($remaining)*] [
            $($expansion)*.with_align(Some($e))
        ])
    };
    (@options_inner [width($e:expr) $($remaining:tt)*] [$($expansion:tt)*]) => {
        $crate::smart_display::padded_width_of!(@options_inner [$($remaining)*] [
            $($expansion)*.with_width(Some($e))
        ])
    };
    (@options_inner [precision($e:expr) $($remaining:tt)*] [$($expansion:tt)*]) => {
        $crate::smart_display::padded_width_of!(@options_inner [$($remaining)*] [
            $($expansion)*.with_precision(Some($e))
        ])
    };
    (@options_inner [alternate($e:expr) $($remaining:tt)*] [$($expansion:tt)*]) => {
        $crate::smart_display::padded_width_of!(@options_inner [$($remaining)*] [
            $($expansion)*.with_width($e)
        ])
    };
    (@options_inner [sign_aware_zero_pad($e:expr) $($remaining:tt)*] [$($expansion:tt)*]) => {
        $crate::smart_display::padded_width_of!(@options_inner [$($remaining)*] [
            $($expansion)*.with_sign_aware_zero_pad($e)
        ])
    };
    // Options entry point
    (@options $($e:tt)*) => {
        $crate::smart_display::padded_width_of!(@options_inner [$($e)*] [
            $crate::smart_display::FormatterOptions::default()
        ])
    };

    // Entry point
    ($($t:tt)*) => {
        $crate::smart_display::padded_width_of!(
            @inner [$($t)*] [0]
        )
    };
}

#[cfg(not(doc))]
pub use __not_public_at_root__padded_width_of as padded_width_of;
#[cfg(doc)]
#[doc(inline)] // Show in this module.
pub use padded_width_of;
/// Implement [`Display`] for a type by using its implementation of [`SmartDisplay`].
///
/// This attribute is applied to the `SmartDisplay` implementation.
///
/// ```rust,no_run
/// # use powerfmt::smart_display::{self, SmartDisplay, Metadata, FormatterOptions};
/// # struct Foo;
/// #[smart_display::delegate]
/// impl SmartDisplay for Foo {
/// #   type Metadata = ();
/// #   fn metadata(&self, f: FormatterOptions) -> Metadata<Self> {
/// #       todo!()
/// #   }
///     // ...
/// }
/// ```
#[cfg(feature = "macros")]
pub use powerfmt_macros::smart_display_delegate as delegate;
/// Declare a private metadata type for `SmartDisplay`.
///
/// Use this attribute if you want to provide metadata for a type that is not public. Doing
/// this will avoid a compiler error about a private type being used publicly. Keep in mind
/// that any public fields, public methods, and trait implementations _will_ be able to be used
/// by downstream users.
///
/// To avoid accidentally exposing details, such as when all fields are public or if the type
/// is a unit struct, the type is annotated with `#[non_exhaustive]` automatically.
///
/// ```rust,no_run
/// # use powerfmt::smart_display;
/// /// Metadata for `Foo`
/// #[smart_display::private_metadata]
/// #[derive(Debug)]
/// pub(crate) struct FooMetadata {
///     pub(crate) expensive_to_calculate: usize,
/// }
/// ```
#[cfg(feature = "macros")]
pub use powerfmt_macros::smart_display_private_metadata as private_metadata;

#[derive(Debug)]
enum FlagBit {
    SignPlus,
    SignMinus,
    Alternate,
    SignAwareZeroPad,
    WidthIsInitialized,
    PrecisionIsInitialized,
}

/// Configuration for formatting.
///
/// This struct is obtained from a [`Formatter`]. It provides the same functionality as that of a
/// reference to a `Formatter`. However, it is not possible to construct a `Formatter`, which is
/// necessary for some use cases of [`SmartDisplay`]. `FormatterOptions` implements [`Default`] and
/// has builder methods to alleviate this.
#[derive(Clone, Copy)]
pub struct FormatterOptions {
    flags: u8,
    fill: char,
    align: Option<Alignment>,
    width: MaybeUninit<usize>,
    precision: MaybeUninit<usize>,
}

impl Debug for FormatterOptions {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.debug_struct("FormatterOptions")
            .field("fill", &self.fill)
            .field("align", &self.align())
            .field("width", &self.width())
            .field("precision", &self.precision())
            .field("sign_plus", &self.sign_plus())
            .field("sign_minus", &self.sign_minus())
            .field("alternate", &self.alternate())
            .field("sign_aware_zero_pad", &self.sign_aware_zero_pad())
            .finish()
    }
}

impl Default for FormatterOptions {
    #[inline]
    fn default() -> Self {
        Self {
            flags: 0,
            fill: ' ',
            align: None,
            width: MaybeUninit::uninit(),
            precision: MaybeUninit::uninit(),
        }
    }
}

impl FormatterOptions {
    /// Sets the fill character to use whenever there is alignment.
    #[inline]
    pub fn with_fill(&mut self, c: char) -> &mut Self {
        self.fill = c;
        self
    }

    /// Set whether the `+` flag is specified.
    #[inline]
    pub fn with_sign_plus(&mut self, b: bool) -> &mut Self {
        if b {
            self.flags |= 1 << FlagBit::SignPlus as u8;
            self.flags &= !(1 << FlagBit::SignMinus as u8);
        } else {
            self.flags &= !(1 << FlagBit::SignPlus as u8);
        }
        self
    }

    /// Set whether the `-` flag is specified.
    #[inline]
    pub fn with_sign_minus(&mut self, b: bool) -> &mut Self {
        if b {
            self.flags |= 1 << FlagBit::SignMinus as u8;
            self.flags &= !(1 << FlagBit::SignPlus as u8);
        } else {
            self.flags &= !(1 << FlagBit::SignMinus as u8);
        }
        self
    }

    /// Set the flag indicating what form of alignment is requested, if any.
    #[inline]
    pub fn with_align(&mut self, align: Option<Alignment>) -> &mut Self {
        self.align = align;
        self
    }

    /// Set the optional integer width that the output should be.
    #[inline]
    pub fn with_width(&mut self, width: Option<usize>) -> &mut Self {
        if let Some(width) = width {
            self.flags |= 1 << FlagBit::WidthIsInitialized as u8;
            self.width = MaybeUninit::new(width);
        } else {
            self.flags &= !(1 << FlagBit::WidthIsInitialized as u8);
        }
        self
    }

    /// Set the optional precision for numeric types. Alternatively, the maximum width for string
    /// types.
    #[inline]
    pub fn with_precision(&mut self, precision: Option<usize>) -> &mut Self {
        if let Some(precision) = precision {
            self.flags |= 1 << FlagBit::PrecisionIsInitialized as u8;
            self.precision = MaybeUninit::new(precision);
        } else {
            self.flags &= !(1 << FlagBit::PrecisionIsInitialized as u8);
        }
        self
    }

    /// Set whether the `#` flag is specified.
    #[inline]
    pub fn with_alternate(&mut self, b: bool) -> &mut Self {
        if b {
            self.flags |= 1 << FlagBit::Alternate as u8;
        } else {
            self.flags &= !(1 << FlagBit::Alternate as u8);
        }
        self
    }

    /// Set whether the `0` flag is specified.
    #[inline]
    pub fn with_sign_aware_zero_pad(&mut self, b: bool) -> &mut Self {
        if b {
            self.flags |= 1 << FlagBit::SignAwareZeroPad as u8;
        } else {
            self.flags &= !(1 << FlagBit::SignAwareZeroPad as u8);
        }
        self
    }
}

impl FormatterOptions {
    /// Character used as 'fill' whenever there is alignment.
    #[inline]
    #[must_use]
    pub const fn fill(&self) -> char {
        self.fill
    }

    /// Flag indicating what form of alignment was requested.
    #[inline]
    #[must_use]
    pub const fn align(&self) -> Option<Alignment> {
        self.align
    }

    /// Optionally specified integer width that the output should be.
    #[inline]
    #[must_use]
    pub const fn width(&self) -> Option<usize> {
        if (self.flags >> FlagBit::WidthIsInitialized as u8) & 1 == 1 {
            // Safety: `width` is initialized if the flag is set.
            Some(unsafe { self.width.assume_init() })
        } else {
            None
        }
    }

    /// Optionally specified precision for numeric types. Alternatively, the maximum width for
    /// string types.
    #[inline]
    #[must_use]
    pub const fn precision(&self) -> Option<usize> {
        if (self.flags >> FlagBit::PrecisionIsInitialized as u8) & 1 == 1 {
            // Safety: `precision` is initialized if the flag is set.
            Some(unsafe { self.precision.assume_init() })
        } else {
            None
        }
    }

    /// Determines if the `+` flag was specified.
    #[inline]
    #[must_use]
    pub const fn sign_plus(&self) -> bool {
        (self.flags >> FlagBit::SignPlus as u8) & 1 == 1
    }

    /// Determines if the `-` flag was specified.
    #[inline]
    #[must_use]
    pub const fn sign_minus(&self) -> bool {
        (self.flags >> FlagBit::SignMinus as u8) & 1 == 1
    }

    /// Determines if the `#` flag was specified.
    #[inline]
    #[must_use]
    pub const fn alternate(&self) -> bool {
        (self.flags >> FlagBit::Alternate as u8) & 1 == 1
    }

    /// Determines if the `0` flag was specified.
    #[inline]
    #[must_use]
    pub const fn sign_aware_zero_pad(&self) -> bool {
        (self.flags >> FlagBit::SignAwareZeroPad as u8) & 1 == 1
    }
}

impl From<&Formatter<'_>> for FormatterOptions {
    fn from(value: &Formatter<'_>) -> Self {
        *Self::default()
            .with_fill(value.fill())
            .with_sign_plus(value.sign_plus())
            .with_sign_minus(value.sign_minus())
            .with_align(value.align())
            .with_width(value.width())
            .with_precision(value.precision())
            .with_alternate(value.alternate())
            .with_sign_aware_zero_pad(value.sign_aware_zero_pad())
    }
}

impl From<&mut Formatter<'_>> for FormatterOptions {
    #[inline]
    fn from(value: &mut Formatter<'_>) -> Self {
        (&*value).into()
    }
}

/// Information used to format a value. This is returned by [`SmartDisplay::metadata`].
///
/// This type is generic over any user-provided type. This allows the author to store any
/// information that is needed. For example, a type's implementation of [`SmartDisplay`] may need
/// to calculate something before knowing its width. This calculation can be performed, with the
/// result being stored in the custom metadata type.
///
/// Note that `Metadata` _always_ contains the width of the type. Authors do not need to store this
/// information in their custom metadata type.
///
/// Generally speaking, a type should be able to be formatted using only its metadata, fields, and
/// the formatter. Any other information should be stored in the metadata type.
pub struct Metadata<'a, T>
where
    T: SmartDisplay + ?Sized,
{
    unpadded_width: usize,
    metadata: T::Metadata,
    _value: PhantomData<&'a T>, // variance
}

// manual impls for bounds
impl<T> Debug for Metadata<'_, T>
where
    T: SmartDisplay,
    T::Metadata: Debug,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.debug_struct("Metadata")
            .field("unpadded_width", &self.unpadded_width)
            .field("metadata", &self.metadata)
            .finish()
    }
}

impl<T> Clone for Metadata<'_, T>
where
    T: SmartDisplay,
    T::Metadata: Clone,
{
    fn clone(&self) -> Self {
        Self {
            unpadded_width: self.unpadded_width,
            metadata: self.metadata.clone(),
            _value: self._value,
        }
    }
}

impl<T> Copy for Metadata<'_, T>
where
    T: SmartDisplay,
    T::Metadata: Copy,
{
}

impl<'a, T> Metadata<'a, T>
where
    T: SmartDisplay + ?Sized,
{
    /// Creates a new `Metadata` with the given width and metadata. While the width _should_ be
    /// exact, this is not a requirement for soundness.
    pub const fn new(unpadded_width: usize, _value: &T, metadata: T::Metadata) -> Self {
        Self {
            unpadded_width,
            metadata,
            _value: PhantomData,
        }
    }

    /// Reuse the metadata for another type. This is useful when implementing [`SmartDisplay`] for a
    /// type that wraps another type. Both type's metadata type must be the same.
    pub fn reuse<'b, U>(self) -> Metadata<'b, U>
    where
        'a: 'b,
        U: SmartDisplay<Metadata = T::Metadata> + ?Sized,
    {
        Metadata {
            unpadded_width: self.unpadded_width,
            metadata: self.metadata,
            _value: PhantomData,
        }
    }

    /// Obtain the width of the value before padding.
    pub const fn unpadded_width(&self) -> usize {
        self.unpadded_width
    }

    /// Obtain the width of the value after padding.
    pub fn padded_width(&self, f: FormatterOptions) -> usize {
        match f.width() {
            Some(requested_width) => cmp::max(self.unpadded_width(), requested_width),
            None => self.unpadded_width(),
        }
    }
}

impl Metadata<'_, Infallible> {
    /// Obtain the width of the value before padding, given the formatter options.
    pub fn unpadded_width_of<T>(value: T, f: FormatterOptions) -> usize
    where
        T: SmartDisplay,
    {
        value.metadata(f).unpadded_width
    }

    /// Obtain the width of the value after padding, given the formatter options.
    pub fn padded_width_of<T>(value: T, f: FormatterOptions) -> usize
    where
        T: SmartDisplay,
    {
        value.metadata(f).padded_width(f)
    }
}

/// Permit using `Metadata` as a smart pointer to the user-provided metadata.
impl<T> Deref for Metadata<'_, T>
where
    T: SmartDisplay + ?Sized,
{
    type Target = T::Metadata;

    fn deref(&self) -> &T::Metadata {
        &self.metadata
    }
}

/// 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.
#[cfg_attr(__powerfmt_docs, rustc_must_implement_one_of(fmt, fmt_with_metadata))]
pub trait SmartDisplay: Display {
    /// User-provided metadata type.
    type Metadata;

    /// 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).
    ///
    /// ```rust,compile_fail
    /// # 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>>(())
    /// ```
    fn metadata(&self, f: FormatterOptions) -> Metadata<'_, Self>;

    /// 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_with_metadata(&self, f: &mut Formatter<'_>, _metadata: Metadata<'_, Self>) -> Result {
        SmartDisplay::fmt(self, f)
    }

    /// 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.
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        let metadata = self.metadata(f.into());
        self.fmt_with_metadata(f, metadata)
    }
}