• Start Date: 2015-01-20
• RFC PR: rust-lang/rfcs#640
• Rust Issue: rust-lang/rust#23083

Summary

The Debug trait is intended to be implemented

Motivation

Pretty printing

The conventions for Debug format state that output should resemble Rust struct

#![allow(unused)]
fn main() {
HashMap { "foo": ComplexType { thing: Some(BufferedReader { reader: FileStream { path: "/home/sfackler/rust/README.md", mode: R }, buffer: 1013/65536 }), other_thing: 100 }, "bar": ComplexType { thing: Some(BufferedReader { reader: FileStream { path: "/tmp/foobar", mode: R }, buffer: 0/65536 }), other_thing: 0 } }
}

This can be made more readable by adding

#![allow(unused)]
fn main() {
HashMap {
    "foo": ComplexType {
        thing: Some(
            BufferedReader {
                reader: FileStream {
                    path: "/home/sfackler/rust/README.md",
                    mode: R
                },
                buffer: 1013/65536
            }
        ),
        other_thing: 100
    },
    "bar": ComplexType {
        thing: Some(
            BufferedReader {
                reader: FileStream {
                    path: "/tmp/foobar",
                    mode: R
                },
                buffer: 0/65536
            }
        ),
        other_thing: 0
    }
}
}

However, we wouldn't want this "pretty printed" version to be used by default, since it's significantly

Helper types

For many Rust types, a Debug implementation

#![allow(unused)]
fn main() {
pub struct BufferedStream<S> {
    inner: BufferedReader<InternalBufferedWriter<S>>
}

impl<S> fmt::Debug for BufferedStream<S> where S: fmt::Debug {
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
        let reader = &self.inner;
        let writer = &self.inner.inner.0;
        write!(fmt, "BufferedStream {{ stream: {:?}, write_buffer: {}/{}, read_buffer: {}/{} }}",
               writer.inner,
               writer.pos, writer.buf.len(),
               reader.cap - reader.pos, reader.buf.len())
    }
}
}

A purely manual

#![allow(unused)]
fn main() {
impl<S> fmt::Debug for BufferedStream<S> where S: fmt::Debug {
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
        let reader = &self.inner;
        let writer = &self.inner.inner.0;
        fmt.debug_struct("BufferedStream")
            .field("stream", writer.inner)
            .field("write_buffer", &format_args!("{}/{}", writer.pos, writer.buf.len()))
            .field("read_buffer", &format_args!("{}/{}", reader.cap - reader.pos, reader.buf.len()))
            .finish()
    }
}
}

Detailed design

設計（する）

Pretty printing

The # modifier (e.g. {:#?}) will be interpreted

• Non-compound output is unchanged from normal Debug output: e.g. 10, "hi", None.
• Array,
  配列
  set
  セットする、集合
  and map output is printed with one element
  要素
  per line, indented four spaces, and entries
  項目
  printed with the # modifier as well: e.g.

#![allow(unused)]
fn main() {
[
    "a",
    "b",
    "c"
]
}

#![allow(unused)]
fn main() {
HashSet {
    "a",
    "b",
    "c"
}
}

#![allow(unused)]
fn main() {
HashMap {
    "a": 1,
    "b": 2,
    "c": 3
}
}

• Struct
  構造、構造体
  and tuple
  タプル(複合型)
  struct
  構造、構造体
  output is printed with one field per line, indented four spaces, and fields printed with the # modifier as well: e.g.

#![allow(unused)]
fn main() {
Foo {
    field1: "hi",
    field2: 10,
    field3: false
}
}

#![allow(unused)]
fn main() {
Foo(
    "hi",
    10,
    false
)
}

In all cases, pretty printed and non-pretty printed output should differ only in the addition

Helper types

Types will be added

#![allow(unused)]
fn main() {
impl Formatter {
    pub fn debug_struct<'a>(&'a mut self, name: &str) -> DebugStruct<'a> { ... }
    pub fn debug_tuple<'a>(&'a mut self, name: &str) -> DebugTuple<'a> { ... }
    pub fn debug_set<'a>(&'a mut self, name: &str) -> DebugSet<'a> { ... }
    pub fn debug_map<'a>(&'a mut self, name: &str) -> DebugMap<'a> { ... }

    pub fn padded<'a>(&'a mut self) -> PaddedWriter<'a> { ... }
}
}

Drawbacks

The use of the # modifier adds complexity to Debug implementations.

The builder types are adding

Alternatives

We could take

Unresolved questions

The indentation level is currently hardcoded to 4 spaces. We could allow