debug3

A space effiecent replacement for [std::fmt::Debug]

The Pitch

Lets say you have data that looks like this:

rust let complex_structure = vec![ vec![None, Some(2)], vec![Some(2), None], vec![Some(4), Some(777)], vec![None, Some(2)], vec![Some(2), None], vec![None, None, None, None, None], ];

And you want to format it as a string. You could use format!("{:?}", complex_structure) and get something like

rust,ignore [[None, Some(2)], [Some(2), None], [Some(4), Some(777)], [None, Some(2)], [Some(2), None], [None, None, None, None, None]]

But this is too much one one line, and is hard to read. And it gets worse for larger structures.

Fortunaly theirs an alternative format!("{:#?}", complex_structure), which gives

rust,ignore [ [ None, Some( 2, ), ], [ Some( 2, ), None, ], [ Some( 4, ), Some( 777, ), ], [ None, Some( 2, ), ], [ Some( 2, ), None, ], [ None, None, None, None, None, ], ]

This has the oposite problem, where it uses too much space, even when the code could be packed denser.

debug3 provides a third option that is denser than :#? but more readable than :?. If you use debug3::pprint(complex_structure), you get

rust,ignore [ [None, Some(2)], [Some(2), None], [Some(4), Some(777)], [None, Some(2)], [Some(2), None], [None, None, None, None, None], ]

Overview

The main entrypoint is the [Debug] trait, which is the equivalent to [std::fmt::Debug], and has a similar API.

This can be either #[derive]d, or implemented manually.

```rust use debug3::{Debug, Formatter, pprint};

[derive(Debug)]

struct MyStruct { a: i32, b: i32, }

struct AnotherStruct { a: i32, b: i32, }

impl Debug for AnotherStruct { fn fmt(&self, f: &mut Formatter) { f.debug_struct("AnotherStruct") .field("a", &self.a) .field("b", &self.b) .finish() } }

asserteq!(pprint(MyStruct { a: 1, b: 2 }), "MyStruct { a: 1, b: 2 }"); asserteq!(pprint(AnotherStruct { a: 1, b: 2 }), "AnotherStruct { a: 1, b: 2 }"); ```

Once your type implements [Debug], you have several options to format it

[pprint]: Convert it to a [String]
[dbg]: Print it to stderr

Comparison to `std::fmt::Debug`:

While the main advantage of debug3 is the superior output quality, it has several drawbacks compared to [std::fmt] that you should know

Commonness: Virtually every type in Rust implements [std::fmt::Debug], vitrualy no types outside of [std] implement [debug3::Debug][Debug].
Availibility: [std::fmt] is also availible as [core::fmt], which allows you to use it in no_std environments. debug3 requires several allocated data structures, so cannot support these environments.
Versitility: [std::fmt::Formatter] has many more API's for implementing [std::fmt::Debug]. In order to achive nice formatting, we cannot accept arbitrary strings, but must have items in the form of Structs, Tuples, Maps, Lists and Sets.
Configurabiliy: We dont suport stuff like format!("{:x?}, 1) to configure how numbers are printed.
Ease of use: We don't have a macro like [std::format] to easily create a string from several elements which implement [Debug]

Prior Art

debug3 would not be possible without all of the following excelent work

core::fmt - The public API of [Formatter] and [builders]
prettyplease - Most of the prety printing algorithm is lifted directly from this crate
custom_debug - The derive macro for [Debug] is based on this crate.
python's pprint - Inspiration for this type of formatting for debug output.

License

^{Licensed under either of Apache License, Version
2.0 or MIT license at your option.}

_{Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.}