Struct Formatter

pub struct Formatter<'a> { pub(in ::fmt) options: FormattingOptions, pub(in ::fmt) buf: &'a mut dyn Write + 'a }

Configuration for formatting.

A Formatter represents various options related to formatting. Users do not construct Formatters directly; a mutable reference to one is passed to the fmt method of all formatting traits, like Debug and Display.

To interact with a Formatter, you'll call various methods to change the various options related to formatting. For examples, please see the documentation of the methods defined on Formatter below.

Fields

options: FormattingOptions
buf: &'a mut dyn Write + 'a

Implementations

impl<'a> Formatter<'a>

fn wrap_buf<'b, 'c, F>(&'b mut self, wrap: F) -> Formatter<'c>
where
    F: FnOnce(&'b mut dyn Write + 'b) -> &'c mut dyn Write + 'c,
    'b: 'c,
fn pad_integral(&mut self, is_nonnegative: bool, prefix: &str, buf: &str) -> Result

Performs the correct padding for an integer which has already been emitted into a str. The str should not contain the sign for the integer, that will be added by this method.

Arguments

  • is_nonnegative - whether the original integer was either positive or zero.
  • prefix - if the '#' character (Alternate) is provided, this is the prefix to put in front of the number.
  • buf - the byte array that the number has been formatted into

This function will correctly account for the flags provided as well as the minimum width. It will not take precision into account.

Examples

use std::fmt;

struct Foo { nb: i32 }

impl Foo {
    fn new(nb: i32) -> Foo {
        Foo {
            nb,
        }
    }
}

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        // We need to remove "-" from the number output.
        let tmp = self.nb.abs().to_string();

        formatter.pad_integral(self.nb >= 0, "Foo ", &tmp)
    }
}

assert_eq!(format!("{}", Foo::new(2)), "2");
assert_eq!(format!("{}", Foo::new(-1)), "-1");
assert_eq!(format!("{}", Foo::new(0)), "0");
assert_eq!(format!("{:#}", Foo::new(-1)), "-Foo 1");
assert_eq!(format!("{:0>#8}", Foo::new(-1)), "00-Foo 1");

fn pad(&mut self, s: &str) -> Result

Takes a string slice and emits it to the internal buffer after applying the relevant formatting flags specified.

The flags recognized for generic strings are:

  • width - the minimum width of what to emit
  • fill/align - what to emit and where to emit it if the string provided needs to be padded
  • precision - the maximum length to emit, the string is truncated if it is longer than this length

Notably this function ignores the flag parameters.

Examples

use std::fmt;

struct Foo;

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.pad("Foo")
    }
}

assert_eq!(format!("{Foo:<4}"), "Foo ");
assert_eq!(format!("{Foo:0>4}"), "0Foo");

fn padding(&mut self, padding: u16, default: Alignment) -> Result<PostPadding, Error>

Writes the pre-padding and returns the unwritten post-padding.

Callers are responsible for ensuring post-padding is written after the thing that is being padded.

unsafe fn pad_formatted_parts(&mut self, formatted: &Formatted<'_>) -> Result

Takes the formatted parts and applies the padding.

Assumes that the caller already has rendered the parts with required precision, so that self.precision can be ignored.

Safety

Any numfmt::Part::Copy parts in formatted must contain valid UTF-8.

unsafe fn write_formatted_parts(&mut self, formatted: &Formatted<'_>) -> Result

Safety

Any numfmt::Part::Copy parts in formatted must contain valid UTF-8.

fn write_str(&mut self, data: &str) -> Result

Writes some data to the underlying buffer contained within this formatter.

Examples

use std::fmt;

struct Foo;

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("Foo")
        // This is equivalent to:
        // write!(formatter, "Foo")
    }
}

assert_eq!(format!("{Foo}"), "Foo");
assert_eq!(format!("{Foo:0>8}"), "Foo");

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result

Glue for usage of the [write!] macro with implementors of this trait.

This method should generally not be invoked manually, but rather through the [write!] macro itself.

Writes some formatted information into this instance.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_fmt(format_args!("Foo {}", self.0))
    }
}

assert_eq!(format!("{}", Foo(-1)), "Foo -1");
assert_eq!(format!("{:0>8}", Foo(2)), "Foo 2");

fn flags(&self) -> u32

Returns flags for formatting.

fn fill(&self) -> char

Returns the character used as 'fill' whenever there is alignment.

Examples

use std::fmt;

struct Foo;

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let c = formatter.fill();
        if let Some(width) = formatter.width() {
            for _ in 0..width {
                write!(formatter, "{c}")?;
            }
            Ok(())
        } else {
            write!(formatter, "{c}")
        }
    }
}

// We set alignment to the right with ">".
assert_eq!(format!("{Foo:G>3}"), "GGG");
assert_eq!(format!("{Foo:t>6}"), "tttttt");

fn align(&self) -> Option<Alignment>

Returns a flag indicating what form of alignment was requested.

Examples

use std::fmt::{self, Alignment};

struct Foo;

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let s = if let Some(s) = formatter.align() {
            match s {
                Alignment::Left    => "left",
                Alignment::Right   => "right",
                Alignment::Center  => "center",
            }
        } else {
            "into the void"
        };
        write!(formatter, "{s}")
    }
}

assert_eq!(format!("{Foo:<}"), "left");
assert_eq!(format!("{Foo:>}"), "right");
assert_eq!(format!("{Foo:^}"), "center");
assert_eq!(format!("{Foo}"), "into the void");

fn width(&self) -> Option<usize>

Returns the optionally specified integer width that the output should be.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Some(width) = formatter.width() {
            // If we received a width, we use it
            write!(formatter, "{:width$}", format!("Foo({})", self.0), width = width)
        } else {
            // Otherwise we do nothing special
            write!(formatter, "Foo({})", self.0)
        }
    }
}

assert_eq!(format!("{:10}", Foo(23)), "Foo(23)   ");
assert_eq!(format!("{}", Foo(23)), "Foo(23)");

fn precision(&self) -> Option<usize>

Returns the optionally specified precision for numeric types. Alternatively, the maximum width for string types.

Examples

use std::fmt;

struct Foo(f32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Some(precision) = formatter.precision() {
            // If we received a precision, we use it.
            write!(formatter, "Foo({1:.*})", precision, self.0)
        } else {
            // Otherwise we default to 2.
            write!(formatter, "Foo({:.2})", self.0)
        }
    }
}

assert_eq!(format!("{:.4}", Foo(23.2)), "Foo(23.2000)");
assert_eq!(format!("{}", Foo(23.2)), "Foo(23.20)");

fn sign_plus(&self) -> bool

Determines if the + flag was specified.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if formatter.sign_plus() {
            write!(formatter,
                   "Foo({}{})",
                   if self.0 < 0 { '-' } else { '+' },
                   self.0.abs())
        } else {
            write!(formatter, "Foo({})", self.0)
        }
    }
}

assert_eq!(format!("{:+}", Foo(23)), "Foo(+23)");
assert_eq!(format!("{:+}", Foo(-23)), "Foo(-23)");
assert_eq!(format!("{}", Foo(23)), "Foo(23)");

fn sign_minus(&self) -> bool

Determines if the - flag was specified.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if formatter.sign_minus() {
            // You want a minus sign? Have one!
            write!(formatter, "-Foo({})", self.0)
        } else {
            write!(formatter, "Foo({})", self.0)
        }
    }
}

assert_eq!(format!("{:-}", Foo(23)), "-Foo(23)");
assert_eq!(format!("{}", Foo(23)), "Foo(23)");

fn alternate(&self) -> bool

Determines if the # flag was specified.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if formatter.alternate() {
            write!(formatter, "Foo({})", self.0)
        } else {
            write!(formatter, "{}", self.0)
        }
    }
}

assert_eq!(format!("{:#}", Foo(23)), "Foo(23)");
assert_eq!(format!("{}", Foo(23)), "23");

fn sign_aware_zero_pad(&self) -> bool

Determines if the 0 flag was specified.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        assert!(formatter.sign_aware_zero_pad());
        assert_eq!(formatter.width(), Some(4));
        // We ignore the formatter's options.
        write!(formatter, "{}", self.0)
    }
}

assert_eq!(format!("{:04}", Foo(23)), "23");

fn debug_lower_hex(&self) -> bool
fn debug_upper_hex(&self) -> bool
fn debug_struct<'b>(&'b mut self, name: &str) -> DebugStruct<'b, 'a>

Creates a DebugStruct builder designed to assist with creation of fmt::Debug implementations for structs.

Examples

use std::fmt;
use std::net::Ipv4Addr;

struct Foo {
    bar: i32,
    baz: String,
    addr: Ipv4Addr,
}

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_struct("Foo")
            .field("bar", &self.bar)
            .field("baz", &self.baz)
            .field("addr", &format_args!("{}", self.addr))
            .finish()
    }
}

assert_eq!(
    "Foo { bar: 10, baz: \"Hello World\", addr: 127.0.0.1 }",
    format!("{:?}", Foo {
        bar: 10,
        baz: "Hello World".to_string(),
        addr: Ipv4Addr::new(127, 0, 0, 1),
    })
);

fn debug_struct_field1_finish<'b>(&'b mut self, name: &str, name1: &str, value1: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_struct_fields_finish is more general, but this is faster for 1 field.

fn debug_struct_field2_finish<'b>(&'b mut self, name: &str, name1: &str, value1: &dyn Debug, name2: &str, value2: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_struct_fields_finish is more general, but this is faster for 2 fields.

fn debug_struct_field3_finish<'b>(&'b mut self, name: &str, name1: &str, value1: &dyn Debug, name2: &str, value2: &dyn Debug, name3: &str, value3: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_struct_fields_finish is more general, but this is faster for 3 fields.

fn debug_struct_field4_finish<'b>(&'b mut self, name: &str, name1: &str, value1: &dyn Debug, name2: &str, value2: &dyn Debug, name3: &str, value3: &dyn Debug, name4: &str, value4: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_struct_fields_finish is more general, but this is faster for 4 fields.

fn debug_struct_field5_finish<'b>(&'b mut self, name: &str, name1: &str, value1: &dyn Debug, name2: &str, value2: &dyn Debug, name3: &str, value3: &dyn Debug, name4: &str, value4: &dyn Debug, name5: &str, value5: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_struct_fields_finish is more general, but this is faster for 5 fields.

fn debug_struct_fields_finish<'b>(&'b mut self, name: &str, names: &[&str], values: &[&dyn Debug]) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. For the cases not covered by debug_struct_field[12345]_finish.

fn debug_c_like_enum_write_str<'b>(&'b mut self, names: &str, offset: &[usize], discr: usize) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. For C-like enums with concatenated variant name strings.

fn debug_tuple<'b>(&'b mut self, name: &str) -> DebugTuple<'b, 'a>

Creates a DebugTuple builder designed to assist with creation of fmt::Debug implementations for tuple structs.

Examples

use std::fmt;
use std::marker::PhantomData;

struct Foo<T>(i32, String, PhantomData<T>);

impl<T> fmt::Debug for Foo<T> {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_tuple("Foo")
            .field(&self.0)
            .field(&self.1)
            .field(&format_args!("_"))
            .finish()
    }
}

assert_eq!(
    "Foo(10, \"Hello\", _)",
    format!("{:?}", Foo(10, "Hello".to_string(), PhantomData::<u8>))
);

fn debug_tuple_field1_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_tuple_fields_finish is more general, but this is faster for 1 field.

fn debug_tuple_field2_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug, value2: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_tuple_fields_finish is more general, but this is faster for 2 fields.

fn debug_tuple_field3_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug, value2: &dyn Debug, value3: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_tuple_fields_finish is more general, but this is faster for 3 fields.

fn debug_tuple_field4_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug, value2: &dyn Debug, value3: &dyn Debug, value4: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_tuple_fields_finish is more general, but this is faster for 4 fields.

fn debug_tuple_field5_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug, value2: &dyn Debug, value3: &dyn Debug, value4: &dyn Debug, value5: &dyn Debug) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. debug_tuple_fields_finish is more general, but this is faster for 5 fields.

fn debug_tuple_fields_finish<'b>(&'b mut self, name: &str, values: &[&dyn Debug]) -> Result

Shrinks derive(Debug) code, for faster compilation and smaller binaries. For the cases not covered by debug_tuple_field[12345]_finish.

fn debug_list<'b>(&'b mut self) -> DebugList<'b, 'a>

Creates a DebugList builder designed to assist with creation of fmt::Debug implementations for list-like structures.

Examples

use std::fmt;

struct Foo(Vec<i32>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_list().entries(self.0.iter()).finish()
    }
}

assert_eq!(format!("{:?}", Foo(vec![10, 11])), "[10, 11]");

fn debug_set<'b>(&'b mut self) -> DebugSet<'b, 'a>

Creates a DebugSet builder designed to assist with creation of fmt::Debug implementations for set-like structures.

Examples

use std::fmt;

struct Foo(Vec<i32>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_set().entries(self.0.iter()).finish()
    }
}

assert_eq!(format!("{:?}", Foo(vec![10, 11])), "{10, 11}");

In this more complex example, we use format_args! and .debug_set() to build a list of match arms:

use std::fmt;

struct Arm<'a, L, R>(&'a (L, R));
struct Table<'a, K, V>(&'a [(K, V)], V);

impl<'a, L, R> fmt::Debug for Arm<'a, L, R>
where
    L: 'a + fmt::Debug, R: 'a + fmt::Debug
{
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        L::fmt(&(self.0).0, fmt)?;
        fmt.write_str(" => ")?;
        R::fmt(&(self.0).1, fmt)
    }
}

impl<'a, K, V> fmt::Debug for Table<'a, K, V>
where
    K: 'a + fmt::Debug, V: 'a + fmt::Debug
{
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_set()
        .entries(self.0.iter().map(Arm))
        .entry(&Arm(&(format_args!("_"), &self.1)))
        .finish()
    }
}

fn debug_map<'b>(&'b mut self) -> DebugMap<'b, 'a>

Creates a DebugMap builder designed to assist with creation of fmt::Debug implementations for map-like structures.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_map().entries(self.0.iter().map(|&(ref k, ref v)| (k, v))).finish()
    }
}

assert_eq!(
    format!("{:?}",  Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{"A": 10, "B": 11}"#
 );

const fn sign(&self) -> Option<Sign>

Returns the sign of this formatter (+ or -).

const fn options(&self) -> FormattingOptions

Returns the formatting options this formatter corresponds to.

impl<'a> Formatter<'a>

const fn new(write: &'a mut dyn Write + 'a, options: FormattingOptions) -> Self

Creates a new formatter with given FormattingOptions.

If write is a reference to a formatter, it is recommended to use Formatter::with_options instead as this can borrow the underlying write, thereby bypassing one layer of indirection.

You may alternatively use [FormattingOptions::create_formatter()].

const fn with_options<'b>(&'b mut self, options: FormattingOptions) -> Formatter<'b>

Creates a new formatter based on this one with given FormattingOptions.

Trait Implementations

impl Write for Formatter<'_>

fn write_str(&mut self, s: &str) -> Result
fn write_char(&mut self, c: char) -> Result
fn write_fmt(&mut self, args: Arguments<'_>) -> Result

Auto Trait Implementations

impl<'a> !RefUnwindSafe for Formatter<'a>

impl<'a> !Send for Formatter<'a>

impl<'a> !Sync for Formatter<'a>

impl<'a> !UnwindSafe for Formatter<'a>

impl<'a> Freeze for Formatter<'a>

impl<'a> Unpin for Formatter<'a>

impl<'a> UnsafeUnpin for Formatter<'a>

Blanket Implementations

impl<T> Any for Formatter<'a> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Formatter<'a> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Formatter<'a> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> From<T> for Formatter<'a>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> SizeHint for Formatter<'a> where T: ?Sized,

fn lower_bound(&self) -> usize
fn upper_bound(&self) -> Option<usize>

impl<T> SizedTypeProperties for Formatter<'a>

impl<T, U> Into<U> for Formatter<'a> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for Formatter<'a> where U: Into<T>,

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for Formatter<'a> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>