Skip to main content

CustomDisplay

custom_display

Trait CustomDisplay 

Source 
pub trait CustomDisplay {
    type Value: ?Sized;

    // Required methods
    fn fmt(&self, value: &Self::Value, f: &mut Formatter<'_>) -> Result;
    fn precision_behavior(&self) -> PrecisionBehavior;
    fn width_in_chars(
        &self,
        value: &Self::Value,
        f: &Formatter<'_>,
    ) -> Option<usize>;

    // Provided methods
    fn auto_width_fill_alignment(&self) -> bool { ... }
    fn default_alignment(&self) -> Alignment { ... }
    fn display<'multi>(
        &'multi self,
        value: &'multi Self::Value,
    ) -> BorrowedDisplayable<'multi, Self> { ... }
    fn into_display(self, value: &Self::Value) -> OwnedDisplayable<'_, Self>
       where Self: Sized { ... }
}
Expand description

A custom format, roughly equivalent to Display except that it is not restricted by coherence.

Displayables that use this trait (created by calling display() or into_display()) can automatically handle width, fill and alignment, as well as precision if precision_behavior() returns AutoTruncate (the behavior specified for non-numeric types).

§Implementation Requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Implementations MUST document how they handle sign, precision, width, fill and alignment.

Most implementations will be unit sructs or type-parameterized tuple structs containing only PhantomData.

Required Associated Types§

Source

type Value: ?Sized

The type of value formatted by this CustomDisplay.

Required Methods§

Source

fn fmt(&self, value: &Self::Value, f: &mut Formatter<'_>) -> Result

Formats and writes a value to the given Formatter.

§Errors

Errors if formatting fails.

§Implementation Requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

If precision is supported by this CustomDisplay and precision_behavior() returns Manual, this method MUST handle it using Formatter::precision().

If sign is supported by this CustomDisplay, this method MUST handle it using Formatter::sign().

If precision_behavior() does not return Manual, this method MUST NOT handle width, fill or alignment. Otherwise, this method MAY handle width, fill and alignment, though it does not need to; those can be automatically handled by Displayable’s Display implementation.

Source

fn precision_behavior(&self) -> PrecisionBehavior

Returns the behavior of a Displayable that uses this CustomDisplay when a precision is set.

Source

fn width_in_chars( &self, value: &Self::Value, f: &Formatter<'_>, ) -> Option<usize>

Returns the width of the value in monospace characters when written by fmt() to a Formatter, or None.

If this method returns None, and auto_width_fill_alignment() returns true or precision_behavior() returns AutoTruncate, formatting will assume all characters have a monospace width of 1 and the width will be computed as the number of characters in the value written by fmt().

§Implementation Requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

If auto_width_fill_alignment() returns false and precision_behavior() returns Manual, this method SHOULD return None. Otherwise, this method MAY return None if both of the following are true:

  • It is safe to assume that all characters written by fmt() have a monospace width of 1.
  • Either:
    • The width cannot be computed more cheaply than by writing it to a String first.
    • One simply doesn’t want to implement it and doesn’t care about the performance cost.

If this method does not return None, it MUST return exactly the number of characters (not bytes!) that would be written by fmt(). As a corrolary, this method MUST take the Formatter into account to the exact same degree that fmt() does.

Provided Methods§

Source

fn auto_width_fill_alignment(&self) -> bool

Returns whether a Displayable using this CustomDisplay will automatically handle width, fill and alignment.

§Implementation Requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

If fmt() handles width, fill and alignment, this method MUST return false.

Otherwise, this method SHOULD return true unless fmt() writes multiple lines of text, as the padding from width, fill and alignment then becomes less helpful.

Source

fn default_alignment(&self) -> Alignment

Returns the Alignment to use if width is set but fill and alignment are not.

§Implementation Notes

By default, this method returns Alignment::Left, as that is the alignment specified by std::fmt for non-numeric types.

Source

fn display<'multi>( &'multi self, value: &'multi Self::Value, ) -> BorrowedDisplayable<'multi, Self>

Returns a wrapper around this CustomDisplay and the given value that implements Display.

See Displayable for more information.

Source

fn into_display(self, value: &Self::Value) -> OwnedDisplayable<'_, Self>
where Self: Sized,

Returns a wrapper around this CustomDisplay and the given value that implements Display and takes ownership of this CustomDisplay.

See Displayable for more information.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§