Formatter in std::fmt - Rust (original) (raw)
pub struct Formatter<'a> { /* private fields */ }Expand description
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.
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.
- 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.
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");This function 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.
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!("{:<4}", Foo), "Foo ");
assert_eq!(&format!("{:0>4}", Foo), "0Foo");Writes some data to the underlying buffer contained within this formatter.
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!("{:0>8}", Foo), "Foo");Writes some formatted information into this instance.
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");👎 Deprecated since 1.24.0:
use the sign_plus, sign_minus, alternate, or sign_aware_zero_pad methods instead
Flags for formatting
Character used as ‘fill’ whenever there is alignment.
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!("{:G>3}", Foo), "GGG");
assert_eq!(&format!("{:t>6}", Foo), "tttttt");Flag indicating what form of alignment was requested.
extern crate core;
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");Optionally specified integer width that the output should be.
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)");Optionally specified precision for numeric types. Alternatively, the maximum width for string types.
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)");Determines if the + flag was specified.
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)
} else {
write!(formatter, "Foo({})", self.0)
}
}
}
assert_eq!(&format!("{:+}", Foo(23)), "Foo(+23)");
assert_eq!(&format!("{}", Foo(23)), "Foo(23)");Determines if the - flag was specified.
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)");Determines if the # flag was specified.
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");Determines if the 0 flag was specified.
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");Creates a DebugStruct builder designed to assist with creation offmt::Debug implementations for structs.
use std::fmt;
use std:🥅: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),
})
);Creates a DebugTuple builder designed to assist with creation offmt::Debug implementations for tuple structs.
use std::fmt;
use std:📑: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>))
);Creates a DebugList builder designed to assist with creation offmt::Debug implementations for list-like structures.
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]");Creates a DebugSet builder designed to assist with creation offmt::Debug implementations for set-like structures.
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: 'a, R: 'a>(&'a (L, R));
struct Table<'a, K: 'a, V: 'a>(&'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()
}
}Creates a DebugMap builder designed to assist with creation offmt::Debug implementations for map-like structures.
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}"#
);Writes a string slice into this writer, returning whether the write succeeded. Read more
Writes a char into this writer, returning whether the write succeeded. Read more
Glue for usage of the write! macro with implementors of this trait. Read more
impl Any for T where
T: 'static + ?Sized,
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
impl From for T
impl<T, U> Into for T where
U: From,
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.