Struct Formatter 

pub struct Formatter<'a> { /* private fields */ }

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.

Implementations

impl<'a> Formatter<'a>

pub const fn new( write: &'a mut dyn Write, options: FormattingOptions, ) -> Formatter<'a>

🔬This is a nightly-only experimental API. (formatting_options #118117)

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().

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

🔬This is a nightly-only experimental API. (formatting_options #118117)

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

impl<'a> Formatter<'a>

pub fn pad_integral( &mut self, is_nonnegative: bool, prefix: &str, buf: &str, ) -> Result<(), Error>

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");

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

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");

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

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");

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

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");

pub fn flags(&self) -> u32

👎Deprecated since 1.24.0:

use the sign_plus, sign_minus, alternate, or sign_aware_zero_pad methods instead

Returns flags for formatting.

pub 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");

pub 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    =>