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()
}
}
assert_eq!(pprint(MyStruct { a: 1, b: 2 }), "MyStruct { a: 1, b: 2 }");
assert_eq!(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
1. Commonness: Virtually every type in Rust implements [`std::fmt::Debug`],
vitrualy no types outside of [`std`] implement [`debug3::Debug`][`Debug`].
2. 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.
3. 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.
4. Configurabiliy: We dont suport stuff like `format!("{:x?}, 1)` to configure
how numbers are printed.
5. 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`](https://github.com/rust-lang/rust/tree/master/library/core/src/fmt) - The public API of [`Formatter`] and `[builders]`
- [`prettyplease`](https://github.com/dtolnay/prettyplease/) - Most of the prety printing algorithm is lifted directly from this crate
- [`custom_debug`](https://github.com/panicbit/custom_debug) - The derive macro for [`Debug`] is based on this crate.
- python's [`pprint`](https://docs.python.org/3/library/pprint.html) - Inspiration for this type of formatting for debug output.
#### License
<sup>
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
</sup>
<br>
<sub>
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.
</sub>