third_party/rust/derive_more-impl/doc/debug.md

   1 # What `#[derive(Debug)]` generates
   2
   3 This derive macro is a clever superset of `Debug` from standard library. Additional features include:
   4 - not imposing redundant trait bounds;
   5 - `#[debug(skip)]` attribute to skip formatting struct field or enum variant;
   6 - `#[debug("...", args...)]` to specify custom formatting for a particular struct or enum variant field;
   7 - `#[debug(bounds(...))]` to impose additional custom trait bounds.
   8
   9
  10
  11
  12 ## The format of the format
  13
  14 You supply a format by placing an attribute on particular struct or enum variant field (not enum variant itself):
  15 `#[debug("...", args...)]`. The format is exactly like in [`format!()`] or any other [`format_args!()`]-based macros.
  16
  17 The variables available in the arguments is `self` and each member of the variant, with members of tuple structs being
  18 named with a leading underscore and their index, i.e. `_0`, `_1`, `_2`, etc.
  19
  20
  21
  22
  23 ### Generic data types
  24
  25 When deriving `Debug` for a generic struct/enum, all generic type arguments _used_ during formatting
  26 are bound by respective formatting trait.
  27
  28 E.g., for a structure `Foo` defined like this:
  29 ```rust
  30 use derive_more::Debug;
  31
  32 #[derive(Debug)]
  33 struct Foo<'a, T1, T2: Trait, T3, T4> {
  34     #[debug("{a}")]
  35     a: T1,
  36     #[debug("{b}")]
  37     b: <T2 as Trait>::Type,
  38     #[debug("{c:?}")]
  39     c: Vec<T3>,
  40     #[debug("{d:p}")]
  41     d: &'a T1,
  42     #[debug(skip)]
  43     e: T4,
  44 }
  45
  46 trait Trait { type Type; }
  47 ```
  48
  49 The following where clauses would be generated:
  50 * `T1: Display + Pointer`
  51 * `<T2 as Trait>::Type: Debug`
  52 * `Bar<T3>: Display`
  53
  54
  55
  56
  57 ### Custom trait bounds
  58
  59 Sometimes you may want to specify additional trait bounds on your generic type parameters, so that they could be used
  60 during formatting. This can be done with a `#[debug(bound(...))]` attribute.
  61
  62 `#[debug(bound(...))]` accepts code tokens in a format similar to the format used in angle bracket list (or `where`
  63 clause predicates): `T: MyTrait, U: Trait1 + Trait2`.
  64
  65 Using `#[debug("...", ...)]` formatting we'll try our best to infer trait bounds, but in more advanced cases this isn't
  66 possible. Our aim is to avoid imposing additional bounds, as they can be added with `#[debug(bound(...))]`.
  67 In the example below, we can infer only that `V: Display`, other bounds have to be supplied by the user:
  68
  69 ```rust
  70 use std::fmt::Display;
  71 use derive_more::Debug;
  72
  73 #[derive(Debug)]
  74 #[debug(bound(T: MyTrait, U: Display))]
  75 struct MyStruct<T, U, V, F> {
  76     #[debug("{}", a.my_function())]
  77     a: T,
  78     #[debug("{}", b.to_string().len())]
  79     b: U,
  80     #[debug("{c}")]
  81     c: V,
  82     #[debug(skip)]
  83     d: F,
  84 }
  85
  86 trait MyTrait { fn my_function(&self) -> i32; }
  87 ```
  88
  89
  90
  91
  92 ## Example usage
  93
  94 ```rust
  95 use std::path::PathBuf;
  96 use derive_more::Debug;
  97
  98 #[derive(Debug)]
  99 struct MyInt(i32);
 100
 101 #[derive(Debug)]
 102 struct MyIntHex(#[debug("{_0:x}")] i32);
 103
 104 #[derive(Debug)]
 105 enum E {
 106     Skipped {
 107         x: u32,
 108         #[debug(skip)]
 109         y: u32,
 110     },
 111     Binary {
 112         #[debug("{i:b}")]
 113         i: i8,
 114     },
 115     Path(#[debug("{}", _0.display())] PathBuf),
 116 }
 117
 118 assert_eq!(format!("{:?}", MyInt(-2)), "MyInt(-2)");
 119 assert_eq!(format!("{:?}", MyIntHex(-255)), "MyIntHex(ffffff01)");
 120 assert_eq!(format!("{:?}", E::Skipped { x: 10, y: 20 }), "Skipped { x: 10, .. }");
 121 assert_eq!(format!("{:?}", E::Binary { i: -2 }), "Binary { i: 11111110 }");
 122 assert_eq!(format!("{:?}", E::Path("abc".into())), "Path(abc)");
 123 ```
 124
 125 [`format!()`]: https://doc.rust-lang.org/stable/std/macro.format.html
 126 [`format_args!()`]: https://doc.rust-lang.org/stable/std/macro.format_args.html