When raw dumps aren't enough
You are building a game. You have a Player struct with health, position, and an inventory. You want to log the player's state to the console during development. You write println!("{}", player). The compiler rejects you with E0277 (trait bound not satisfied). You fix the error by implementing Display, but now the output is Player { health: 100, position: (10, 20), inventory: [...] }. That structure dump is useful for debugging, but your game UI needs "Player: 100 HP @ (10, 20)". You need control over how your type turns into text. That is where Display comes in.
Rust separates formatting into two distinct lanes. Debug is the raw dump. It is for you, the developer, to see exactly what is inside a value. Display is the polished presentation. It is for the end user. Think of Debug as the raw JSON payload an API returns. Display is the rendered HTML page. You implement Display when you want your type to speak human-readable text.
Display versus Debug
The Debug trait exists for inspection. It shows the internal structure, field names, and raw values. The Display trait exists for communication. It shows what the value means to the person reading it.
A timestamp type might implement Debug to show Timestamp { seconds: 1678886400, nanos: 0 }. That is precise and unambiguous for a developer. The same type might implement Display to show 2023-03-15 12:00:00 UTC. That is readable for a user.
Rust provides {:?} for Debug and {} for Display. The syntax tells the compiler which trait to call. If you use {} on a type that only has Debug, the compiler stops you. This separation prevents accidental leakage of internal state into user-facing output. It also forces you to think about the audience for your text representation.
Derive Debug for every type you create. Implement Display only when the text representation is meaningful to the end user.
The minimal implementation
Implementing Display requires an impl block for std::fmt::Display. You must provide a fmt method that takes a reference to a Formatter and returns a fmt::Result. The write! macro writes formatted text into the formatter.
use std::fmt;
/// Represents a coordinate in 2D space.
struct Point {
x: f64,
y: f64,
}
// Implement Display to control how Point appears in user-facing output.
impl fmt::Display for Point {
// The fmt method receives a formatter and returns a Result.
// The formatter handles width, alignment, and precision flags.
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Use write! to format the string into the formatter.
// This writes directly to the formatter's buffer without allocating a String.
write!(f, "({}, {})", self.x, self.y)
}
}
fn main() {
let p = Point { x: 10.0, y: 20.0 };
// {} uses Display.
println!("{}", p); // Output: (10, 20)
// {:>10} uses Display with right-alignment and width 10.
println!("{:>10}", p); // Output: " (10, 20)"
}
The write! macro is the standard way to produce output in fmt. It expands to a call that writes into the formatter. It respects formatting flags automatically. If the user requests width or alignment, write! applies those constraints to the output. You do not need to parse the flags yourself.
The write! macro writes directly to the formatter without allocating a temporary string. Use write! in fmt implementations. Avoid format! inside fmt, as that allocates a heap buffer just to copy it into the formatter.
How the formatter works
The &mut fmt::Formatter argument is not just a buffer. It carries metadata about how the user wants the value formatted. The formatter tracks flags like width, alignment, precision, and the alternate flag (#).
When you use {:>10} in a format string, the formatter knows to right-align the output and pad it to a width of 10. When you use {:.2} on a float, the formatter knows to limit precision to two decimal places. Your write! call respects these flags automatically if you use the correct placeholders.
use std::fmt;
struct Ratio {
numerator: u32,
denominator: u32,
}
impl fmt::Display for Ratio {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// The formatter handles precision for the float division.
// If the user writes {:.3}, this outputs three decimal places.
let value = self.numerator as f64 / self.denominator as f64;
write!(f, "{}", value)
}
}
fn main() {
let r = Ratio { numerator: 1, denominator: 3 };
println!("{}", r); // Output: 0.3333333333333333
println!("{:.2}", r); // Output: 0.33
}
The formatter does the heavy lifting. You provide the data; it handles the layout. Trust the formatter to apply flags to your write! arguments. You can query the formatter for specific flags if you need custom behavior. Methods like f.width(), f.align(), and f.alternate() let you inspect the requested formatting.
Generics and trait bounds
Generic types often need Display implementations. If your type holds a generic parameter T, and you want to display T, then T must implement Display. You express this with a trait bound on the impl block.
use std::fmt;
/// A generic pair of values.
struct Pair<T> {
first: T,
second: T,
}
// T must implement Display for Pair to implement Display.
// Without this bound, the compiler cannot guarantee T can be formatted.
impl<T: fmt::Display> fmt::Display for Pair<T> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Format both elements using their own Display implementations.
// The trait bound ensures this code is valid.
write!(f, "({}, {})", self.first, self.second)
}
}
fn main() {
let numbers = Pair { first: 1, second: 2 };
let words = Pair { first: "hello".to_string(), second: "world".to_string() };
println!("{}", numbers); // Output: (1, 2)
println!("{}", words); // Output: (hello, world)
}
If you drop the T: fmt::Display bound, the compiler rejects the code with E0277. It tells you that T does not implement Display, so you cannot use {} on it. You must add the bound to tell the compiler that Pair<T> only supports Display when T does too.
Generic types inherit constraints. If your type holds a T, and you want to display it, T must be displayable. Add the trait bound to the impl block to satisfy the compiler.
Handling complexity and options
Real-world types often contain optional fields or nested structures. You need to handle Option gracefully and propagate formatting errors. The fmt::Result type is a Result<(), fmt::Error>. You can use the ? operator to propagate errors.
use std::fmt;
/// A user profile with an optional email.
struct User {
name: String,
email: Option<String>,
}
impl fmt::Display for User {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Write the name first.
// The ? operator propagates any formatting error immediately.
write!(f, "{}", self.name)?;
// Handle optional email gracefully.
// Only append email if it exists.
if let Some(email) = &self.email {
write!(f, " <{}>", email)?;
}
Ok(())
}
}
fn main() {
let u1 = User { name: "Alice".to_string(), email: Some("alice@example.com".to_string()) };
let u2 = User { name: "Bob".to_string(), email: None };
println!("{}", u1); // Output: Alice <alice@example.com>
println!("{}", u2); // Output: Bob
}
The ? operator works in fmt because fmt::Result implements From<fmt::Error>. It keeps your implementation clean. You do not need to match on Ok and Err. Just chain write! calls with ?.
Propagate formatting errors. The ? operator keeps your fmt implementation clean and safe. Ignoring the return value of write! triggers a warning and hides potential errors.
Advanced flags and precision
Some types benefit from supporting formatting flags. The alternate flag (#) is common for numbers. Users expect # to add prefixes like 0b for binary or 0x for hexadecimal. You can check f.alternate() to detect this flag.
use std::fmt;
/// A wrapper around a u32 that displays as binary.
struct BinaryNumber(u32);
impl fmt::Display for BinaryNumber {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Check for alternate flag (#).
// If present, add the 0b prefix.
if f.alternate() {
write!(f, "0b{:b}", self.0)
} else {
write!(f, "{:b}", self.0)
}
}
}
fn main() {
let n = BinaryNumber(5);
println!("{}", n); // Output: 101
println!("{:#}", n); // Output: 0b101
}
The precision flag can also be useful. For floating-point types, precision controls decimal places. For strings, it limits the number of characters. You can query f.precision() to get an Option<usize>. If the user specifies precision, use it. If not, fall back to a default.
Check f.alternate() to support the # flag. Users expect # to add prefixes or alternate representations. Respect the convention.
Pitfalls and conventions
Missing trait bounds are the most common error. If you implement Display for a generic type and forget the bound on the generic parameter, you get E0277. The compiler will point to the write! call where the bound is required. Add the bound to the impl block.
Another pitfall is forgetting Debug. Always derive Debug for your types. #[derive(Debug)] is cheap and provides a fallback for inspection. If you only implement Display, you lose the ability to debug your type easily.
#[derive(Debug)]
struct Point {
x: f64,
y: f64,
}
There is a convention around Rc::clone that applies here too. When calling clone on an Rc, write Rc::clone(&data) instead of data.clone(). The explicit form makes it clear you are cloning the reference, not the inner data. Similarly, in fmt implementations, be explicit about what you are formatting. Use write!(f, "{}", value) rather than hiding the formatting logic.
Implementing Display gives you ToString for free. Rust has a blanket implementation: impl<T: Display> ToString for T. You do not need to implement ToString separately. If you have Display, you can call .to_string() on your type. This is a common surprise for beginners who implement both traits.
Derive Debug for every type. Implement Display only when the text representation matters to the user. Trust the blanket implementation for ToString.
Decision matrix
Use Display when you need user-facing text. This includes UI labels, log messages meant for operators, and export formats like CSV or JSON strings.
Use Debug when you need developer-facing dumps. This covers logging during development, error messages that include internal state, and test assertions.
Use #[derive(Debug)] for every type you create. It costs nothing and saves hours of debugging.
Use Display only when the text representation is meaningful to the end user. If the type is an internal helper, stick to Debug.
Reach for ToString only when you explicitly need a String value. If you have Display, you automatically get ToString via the blanket implementation. Calling .to_string() allocates a new heap buffer; prefer formatting macros when possible to avoid allocation.