/// macro validates the format string at compile-time so usage of the [`write`]
/// and [`format`] functions can be safely performed.
///
+/// You can use the `Arguments<'a>` that [`format_args!`] returns in `Debug`
+/// and `Display` contexts as seen below. The example also shows that `Debug`
+/// and `Display` format to the same thing: the interpolated format string
+/// in `format_args!`.
+///
+/// ```rust
+/// let display = format!("{:?}", format_args!("{} foo {:?}", 1, 2));
+/// let debug = format!("{}", format_args!("{} foo {:?}", 1, 2));
+/// assert_eq!("1 foo 2", display);
+/// assert_eq!(display, debug);
+/// ```
+///
/// [`format_args!`]: ../../std/macro.format_args.html
/// [`format`]: ../../std/fmt/fn.format.html
/// [`write`]: ../../std/fmt/fn.write.html
///
/// ```rust
/// use std::fmt;
+ /// use std::net::Ipv4Addr;
///
/// struct Foo {
/// bar: i32,
/// baz: String,
+ /// addr: Ipv4Addr,
/// }
///
/// impl fmt::Debug for Foo {
/// fmt.debug_struct("Foo")
/// .field("bar", &self.bar)
/// .field("baz", &self.baz)
+ /// .field("addr", &format_args!("{}", self.addr))
/// .finish()
/// }
/// }
///
- /// // prints "Foo { bar: 10, baz: "Hello World" }"
- /// println!("{:?}", Foo { bar: 10, baz: "Hello World".to_string() });
+ /// assert_eq!(
+ /// "Foo { bar: 10, baz: \"Hello World\", addr: 127.0.0.1 }",
+ /// format!("{:?}", Foo {
+ /// bar: 10,
+ /// baz: "Hello World".to_string(),
+ /// addr: Ipv4Addr::new(127, 0, 0, 1),
+ /// })
+ /// );
/// ```
#[stable(feature = "debug_builders", since = "1.2.0")]
pub fn debug_struct<'b>(&'b mut self, name: &str) -> DebugStruct<'b, 'a> {
///
/// ```rust
/// use std::fmt;
+ /// use std::marker::PhantomData;
///
- /// struct Foo(i32, String);
+ /// struct Foo<T>(i32, String, PhantomData<T>);
///
- /// impl fmt::Debug for Foo {
+ /// impl<T> fmt::Debug for Foo<T> {
/// fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
/// fmt.debug_tuple("Foo")
/// .field(&self.0)
/// .field(&self.1)
+ /// .field(&format_args!("_"))
/// .finish()
/// }
/// }
///
- /// // prints "Foo(10, "Hello World")"
- /// println!("{:?}", Foo(10, "Hello World".to_string()));
+ /// assert_eq!(
+ /// "Foo(10, \"Hello\", _)",
+ /// format!("{:?}", Foo(10, "Hello".to_string(), PhantomData::<u8>))
+ /// );
/// ```
#[stable(feature = "debug_builders", since = "1.2.0")]
pub fn debug_tuple<'b>(&'b mut self, name: &str) -> DebugTuple<'b, 'a> {
/// // prints "{10, 11}"
/// println!("{:?}", Foo(vec![10, 11]));
/// ```
+ ///
+ /// [`format_args!`]: ../../std/macro.format_args.html
+ ///
+ /// In this more complex example, we use [`format_args!`] and `.debug_set()`
+ /// to build a list of match arms:
+ ///
+ /// ```rust
+ /// use std::fmt;
+ ///
+ /// struct Arm<'a, L: 'a, R: 'a>(&'a (L, R));
+ /// struct Table<'a, K: 'a, V: 'a>(&'a [(K, V)], V);
+ ///
+ /// impl<'a, L, R> fmt::Debug for Arm<'a, L, R>
+ /// where
+ /// L: 'a + fmt::Debug, R: 'a + fmt::Debug
+ /// {
+ /// fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
+ /// L::fmt(&(self.0).0, fmt)?;
+ /// fmt.write_str(" => ")?;
+ /// R::fmt(&(self.0).1, fmt)
+ /// }
+ /// }
+ ///
+ /// impl<'a, K, V> fmt::Debug for Table<'a, K, V>
+ /// where
+ /// K: 'a + fmt::Debug, V: 'a + fmt::Debug
+ /// {
+ /// fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
+ /// fmt.debug_set()
+ /// .entries(self.0.iter().map(Arm))
+ /// .entry(&Arm(&(format_args!("_"), &self.1)))
+ /// .finish()
+ /// }
+ /// }
+ /// ```
#[stable(feature = "debug_builders", since = "1.2.0")]
pub fn debug_set<'b>(&'b mut self) -> DebugSet<'b, 'a> {
builders::debug_set_new(self)