#
core/fmt/
builders.rs

    1#![allow(unused_imports)]
    2
    3use crate::fmt::{self, Debug, Formatter};
    4
    5struct PadAdapter<'buf, 'state> {
    6    buf: &'buf mut (dyn fmt::Write + 'buf),
    7    state: &'state mut PadAdapterState,
    8}
    9
    10struct PadAdapterState {
    11    on_newline: bool,
    12}
    13
    14impl Default for PadAdapterState {
    15    fn default() -> Self {
    16        PadAdapterState { on_newline: true }
    17    }
    18}
    19
    20impl<'buf, 'state> PadAdapter<'buf, 'state> {
    21    fn wrap<'slot, 'fmt: 'buf + 'slot>(
    22        fmt: &'fmt mut fmt::Formatter<'_>,
    23        slot: &'slot mut Option<Self>,
    24        state: &'state mut PadAdapterState,
    25    ) -> fmt::Formatter<'slot> {
    26        fmt.wrap_buf(move |buf| slot.insert(PadAdapter { buf, state }))
    27    }
    28}
    29
    30impl fmt::Write for PadAdapter<'_, '_> {
    31    fn write_str(&mut self, s: &str) -> fmt::Result {
    32        for s in s.split_inclusive('\n') {
    33            if self.state.on_newline {
    34                self.buf.write_str("    ")?;
    35            }
    36
    37            self.state.on_newline = s.ends_with('\n');
    38            self.buf.write_str(s)?;
    39        }
    40
    41        Ok(())
    42    }
    43
    44    fn write_char(&mut self, c: char) -> fmt::Result {
    45        if self.state.on_newline {
    46            self.buf.write_str("    ")?;
    47        }
    48        self.state.on_newline = c == '\n';
    49        self.buf.write_char(c)
    50    }
    51}
    52
    53/// A struct to help with [`fmt::Debug`](Debug) implementations.
    54///
    55/// This is useful when you wish to output a formatted struct as a part of your
    56/// [`Debug::fmt`] implementation.
    57///
    58/// This can be constructed by the [`Formatter::debug_struct`] method.
    59///
    60/// # Examples
    61///
    62/// ```
    63/// use std::fmt;
    64///
    65/// struct Foo {
    66///     bar: i32,
    67///     baz: String,
    68/// }
    69///
    70/// impl fmt::Debug for Foo {
    71///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    72///         fmt.debug_struct("Foo")
    73///            .field("bar", &self.bar)
    74///            .field("baz", &self.baz)
    75///            .finish()
    76///     }
    77/// }
    78///
    79/// assert_eq!(
    80///     format!("{:?}", Foo { bar: 10, baz: "Hello World".to_string() }),
    81///     r#"Foo { bar: 10, baz: "Hello World" }"#,
    82/// );
    83/// ```
    84#[must_use = "must eventually call `finish()` on Debug builders"]
    85#[allow(missing_debug_implementations)]
    86#[stable(feature = "debug_builders", since = "1.2.0")]
    87#[rustc_diagnostic_item = "DebugStruct"]
    88pub struct DebugStruct<'a, 'b: 'a> {
    89    fmt: &'a mut fmt::Formatter<'b>,
    90    result: fmt::Result,
    91    has_fields: bool,
    92}
    93
    94pub(super) fn debug_struct_new<'a, 'b>(
    95    fmt: &'a mut fmt::Formatter<'b>,
    96    name: &str,
    97) -> DebugStruct<'a, 'b> {
    98    let result = fmt.write_str(name);
    99    DebugStruct { fmt, result, has_fields: false }
    100}
    101
    102impl<'a, 'b: 'a> DebugStruct<'a, 'b> {
    103    /// Adds a new field to the generated struct output.
    104    ///
    105    /// # Examples
    106    ///
    107    /// ```
    108    /// use std::fmt;
    109    ///
    110    /// struct Bar {
    111    ///     bar: i32,
    112    ///     another: String,
    113    /// }
    114    ///
    115    /// impl fmt::Debug for Bar {
    116    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    117    ///         fmt.debug_struct("Bar")
    118    ///            .field("bar", &self.bar) // We add `bar` field.
    119    ///            .field("another", &self.another) // We add `another` field.
    120    ///            // We even add a field which doesn't exist (because why not?).
    121    ///            .field("nonexistent_field", &1)
    122    ///            .finish() // We're good to go!
    123    ///     }
    124    /// }
    125    ///
    126    /// assert_eq!(
    127    ///     format!("{:?}", Bar { bar: 10, another: "Hello World".to_string() }),
    128    ///     r#"Bar { bar: 10, another: "Hello World", nonexistent_field: 1 }"#,
    129    /// );
    130    /// ```
    131    #[stable(feature = "debug_builders", since = "1.2.0")]
    132    pub fn field(&mut self, name: &str, value: &dyn fmt::Debug) -> &mut Self {
    133        self.field_with(name, |f| value.fmt(f))
    134    }
    135
    136    /// Adds a new field to the generated struct output.
    137    ///
    138    /// This method is equivalent to [`DebugStruct::field`], but formats the
    139    /// value using a provided closure rather than by calling [`Debug::fmt`].
    140    #[unstable(feature = "debug_closure_helpers", issue = "117729")]
    141    pub fn field_with<F>(&mut self, name: &str, value_fmt: F) -> &mut Self
    142    where
    143        F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result,
    144    {
    145        self.result = self.result.and_then(|_| {
    146            if self.is_pretty() {
    147                if !self.has_fields {
    148                    self.fmt.write_str(" {\n")?;
    149                }
    150                let mut slot = None;
    151                let mut state = Default::default();
    152                let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state);
    153                writer.write_str(name)?;
    154                writer.write_str(": ")?;
    155                value_fmt(&mut writer)?;
    156                writer.write_str(",\n")
    157            } else {
    158                let prefix = if self.has_fields { ", " } else { " { " };
    159                self.fmt.write_str(prefix)?;
    160                self.fmt.write_str(name)?;
    161                self.fmt.write_str(": ")?;
    162                value_fmt(self.fmt)
    163            }
    164        });
    165
    166        self.has_fields = true;
    167        self
    168    }
    169
    170    /// Marks the struct as non-exhaustive, indicating to the reader that there are some other
    171    /// fields that are not shown in the debug representation.
    172    ///
    173    /// # Examples
    174    ///
    175    /// ```
    176    /// use std::fmt;
    177    ///
    178    /// struct Bar {
    179    ///     bar: i32,
    180    ///     hidden: f32,
    181    /// }
    182    ///
    183    /// impl fmt::Debug for Bar {
    184    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    185    ///         fmt.debug_struct("Bar")
    186    ///            .field("bar", &self.bar)
    187    ///            .finish_non_exhaustive() // Show that some other field(s) exist.
    188    ///     }
    189    /// }
    190    ///
    191    /// assert_eq!(
    192    ///     format!("{:?}", Bar { bar: 10, hidden: 1.0 }),
    193    ///     "Bar { bar: 10, .. }",
    194    /// );
    195    /// ```
    196    #[stable(feature = "debug_non_exhaustive", since = "1.53.0")]
    197    pub fn finish_non_exhaustive(&mut self) -> fmt::Result {
    198        self.result = self.result.and_then(|_| {
    199            if self.has_fields {
    200                if self.is_pretty() {
    201                    let mut slot = None;
    202                    let mut state = Default::default();
    203                    let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state);
    204                    writer.write_str("..\n")?;
    205                    self.fmt.write_str("}")
    206                } else {
    207                    self.fmt.write_str(", .. }")
    208                }
    209            } else {
    210                self.fmt.write_str(" { .. }")
    211            }
    212        });
    213        self.result
    214    }
    215
    216    /// Finishes output and returns any error encountered.
    217    ///
    218    /// # Examples
    219    ///
    220    /// ```
    221    /// use std::fmt;
    222    ///
    223    /// struct Bar {
    224    ///     bar: i32,
    225    ///     baz: String,
    226    /// }
    227    ///
    228    /// impl fmt::Debug for Bar {
    229    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    230    ///         fmt.debug_struct("Bar")
    231    ///            .field("bar", &self.bar)
    232    ///            .field("baz", &self.baz)
    233    ///            .finish() // You need to call it to "finish" the
    234    ///                      // struct formatting.
    235    ///     }
    236    /// }
    237    ///
    238    /// assert_eq!(
    239    ///     format!("{:?}", Bar { bar: 10, baz: "Hello World".to_string() }),
    240    ///     r#"Bar { bar: 10, baz: "Hello World" }"#,
    241    /// );
    242    /// ```
    243    #[stable(feature = "debug_builders", since = "1.2.0")]
    244    pub fn finish(&mut self) -> fmt::Result {
    245        if self.has_fields {
    246            self.result = self.result.and_then(|_| {
    247                if self.is_pretty() { self.fmt.write_str("}") } else { self.fmt.write_str(" }") }
    248            });
    249        }
    250        self.result
    251    }
    252
    253    fn is_pretty(&self) -> bool {
    254        self.fmt.alternate()
    255    }
    256}
    257
    258/// A struct to help with [`fmt::Debug`](Debug) implementations.
    259///
    260/// This is useful when you wish to output a formatted tuple as a part of your
    261/// [`Debug::fmt`] implementation.
    262///
    263/// This can be constructed by the [`Formatter::debug_tuple`] method.
    264///
    265/// # Examples
    266///
    267/// ```
    268/// use std::fmt;
    269///
    270/// struct Foo(i32, String);
    271///
    272/// impl fmt::Debug for Foo {
    273///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    274///         fmt.debug_tuple("Foo")
    275///            .field(&self.0)
    276///            .field(&self.1)
    277///            .finish()
    278///     }
    279/// }
    280///
    281/// assert_eq!(
    282///     format!("{:?}", Foo(10, "Hello World".to_string())),
    283///     r#"Foo(10, "Hello World")"#,
    284/// );
    285/// ```
    286#[must_use = "must eventually call `finish()` on Debug builders"]
    287#[allow(missing_debug_implementations)]
    288#[stable(feature = "debug_builders", since = "1.2.0")]
    289pub struct DebugTuple<'a, 'b: 'a> {
    290    fmt: &'a mut fmt::Formatter<'b>,
    291    result: fmt::Result,
    292    fields: usize,
    293    empty_name: bool,
    294}
    295
    296pub(super) fn debug_tuple_new<'a, 'b>(
    297    fmt: &'a mut fmt::Formatter<'b>,
    298    name: &str,
    299) -> DebugTuple<'a, 'b> {
    300    let result = fmt.write_str(name);
    301    DebugTuple { fmt, result, fields: 0, empty_name: name.is_empty() }
    302}
    303
    304impl<'a, 'b: 'a> DebugTuple<'a, 'b> {
    305    /// Adds a new field to the generated tuple struct output.
    306    ///
    307    /// # Examples
    308    ///
    309    /// ```
    310    /// use std::fmt;
    311    ///
    312    /// struct Foo(i32, String);
    313    ///
    314    /// impl fmt::Debug for Foo {
    315    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    316    ///         fmt.debug_tuple("Foo")
    317    ///            .field(&self.0) // We add the first field.
    318    ///            .field(&self.1) // We add the second field.
    319    ///            .finish() // We're good to go!
    320    ///     }
    321    /// }
    322    ///
    323    /// assert_eq!(
    324    ///     format!("{:?}", Foo(10, "Hello World".to_string())),
    325    ///     r#"Foo(10, "Hello World")"#,
    326    /// );
    327    /// ```
    328    #[stable(feature = "debug_builders", since = "1.2.0")]
    329    pub fn field(&mut self, value: &dyn fmt::Debug) -> &mut Self {
    330        self.field_with(|f| value.fmt(f))
    331    }
    332
    333    /// Adds a new field to the generated tuple struct output.
    334    ///
    335    /// This method is equivalent to [`DebugTuple::field`], but formats the
    336    /// value using a provided closure rather than by calling [`Debug::fmt`].
    337    #[unstable(feature = "debug_closure_helpers", issue = "117729")]
    338    pub fn field_with<F>(&mut self, value_fmt: F) -> &mut Self
    339    where
    340        F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result,
    341    {
    342        self.result = self.result.and_then(|_| {
    343            if self.is_pretty() {
    344                if self.fields == 0 {
    345                    self.fmt.write_str("(\n")?;
    346                }
    347                let mut slot = None;
    348                let mut state = Default::default();
    349                let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state);
    350                value_fmt(&mut writer)?;
    351                writer.write_str(",\n")
    352            } else {
    353                let prefix = if self.fields == 0 { "(" } else { ", " };
    354                self.fmt.write_str(prefix)?;
    355                value_fmt(self.fmt)
    356            }
    357        });
    358
    359        self.fields += 1;
    360        self
    361    }
    362
    363    /// Marks the tuple struct as non-exhaustive, indicating to the reader that there are some
    364    /// other fields that are not shown in the debug representation.
    365    ///
    366    /// # Examples
    367    ///
    368    /// ```
    369    /// use std::fmt;
    370    ///
    371    /// struct Foo(i32, String);
    372    ///
    373    /// impl fmt::Debug for Foo {
    374    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    375    ///         fmt.debug_tuple("Foo")
    376    ///            .field(&self.0)
    377    ///            .finish_non_exhaustive() // Show that some other field(s) exist.
    378    ///     }
    379    /// }
    380    ///
    381    /// assert_eq!(
    382    ///     format!("{:?}", Foo(10, "secret!".to_owned())),
    383    ///     "Foo(10, ..)",
    384    /// );
    385    /// ```
    386    #[stable(feature = "debug_more_non_exhaustive", since = "1.83.0")]
    387    pub fn finish_non_exhaustive(&mut self) -> fmt::Result {
    388        self.result = self.result.and_then(|_| {
    389            if self.fields > 0 {
    390                if self.is_pretty() {
    391                    let mut slot = None;
    392                    let mut state = Default::default();
    393                    let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state);
    394                    writer.write_str("..\n")?;
    395                    self.fmt.write_str(")")
    396                } else {
    397                    self.fmt.write_str(", ..)")
    398                }
    399            } else {
    400                self.fmt.write_str("(..)")
    401            }
    402        });
    403        self.result
    404    }
    405
    406    /// Finishes output and returns any error encountered.
    407    ///
    408    /// # Examples
    409    ///
    410    /// ```
    411    /// use std::fmt;
    412    ///
    413    /// struct Foo(i32, String);
    414    ///
    415    /// impl fmt::Debug for Foo {
    416    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    417    ///         fmt.debug_tuple("Foo")
    418    ///            .field(&self.0)
    419    ///            .field(&self.1)
    420    ///            .finish() // You need to call it to "finish" the
    421    ///                      // tuple formatting.
    422    ///     }
    423    /// }
    424    ///
    425    /// assert_eq!(
    426    ///     format!("{:?}", Foo(10, "Hello World".to_string())),
    427    ///     r#"Foo(10, "Hello World")"#,
    428    /// );
    429    /// ```
    430    #[stable(feature = "debug_builders", since = "1.2.0")]
    431    pub fn finish(&mut self) -> fmt::Result {
    432        if self.fields > 0 {
    433            self.result = self.result.and_then(|_| {
    434                if self.fields == 1 && self.empty_name && !self.is_pretty() {
    435                    self.fmt.write_str(",")?;
    436                }
    437                self.fmt.write_str(")")
    438            });
    439        }
    440        self.result
    441    }
    442
    443    fn is_pretty(&self) -> bool {
    444        self.fmt.alternate()
    445    }
    446}
    447
    448/// A helper used to print list-like items with no special formatting.
    449struct DebugInner<'a, 'b: 'a> {
    450    fmt: &'a mut fmt::Formatter<'b>,
    451    result: fmt::Result,
    452    has_fields: bool,
    453}
    454
    455impl<'a, 'b: 'a> DebugInner<'a, 'b> {
    456    fn entry_with<F>(&mut self, entry_fmt: F)
    457    where
    458        F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result,
    459    {
    460        self.result = self.result.and_then(|_| {
    461            if self.is_pretty() {
    462                if !self.has_fields {
    463                    self.fmt.write_str("\n")?;
    464                }
    465                let mut slot = None;
    466                let mut state = Default::default();
    467                let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state);
    468                entry_fmt(&mut writer)?;
    469                writer.write_str(",\n")
    470            } else {
    471                if self.has_fields {
    472                    self.fmt.write_str(", ")?
    473                }
    474                entry_fmt(self.fmt)
    475            }
    476        });
    477
    478        self.has_fields = true;
    479    }
    480
    481    fn is_pretty(&self) -> bool {
    482        self.fmt.alternate()
    483    }
    484}
    485
    486/// A struct to help with [`fmt::Debug`](Debug) implementations.
    487///
    488/// This is useful when you wish to output a formatted set of items as a part
    489/// of your [`Debug::fmt`] implementation.
    490///
    491/// This can be constructed by the [`Formatter::debug_set`] method.
    492///
    493/// # Examples
    494///
    495/// ```
    496/// use std::fmt;
    497///
    498/// struct Foo(Vec<i32>);
    499///
    500/// impl fmt::Debug for Foo {
    501///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    502///         fmt.debug_set().entries(self.0.iter()).finish()
    503///     }
    504/// }
    505///
    506/// assert_eq!(
    507///     format!("{:?}", Foo(vec![10, 11])),
    508///     "{10, 11}",
    509/// );
    510/// ```
    511#[must_use = "must eventually call `finish()` on Debug builders"]
    512#[allow(missing_debug_implementations)]
    513#[stable(feature = "debug_builders", since = "1.2.0")]
    514pub struct DebugSet<'a, 'b: 'a> {
    515    inner: DebugInner<'a, 'b>,
    516}
    517
    518pub(super) fn debug_set_new<'a, 'b>(fmt: &'a mut fmt::Formatter<'b>) -> DebugSet<'a, 'b> {
    519    let result = fmt.write_str("{");
    520    DebugSet { inner: DebugInner { fmt, result, has_fields: false } }
    521}
    522
    523impl<'a, 'b: 'a> DebugSet<'a, 'b> {
    524    /// Adds a new entry to the set output.
    525    ///
    526    /// # Examples
    527    ///
    528    /// ```
    529    /// use std::fmt;
    530    ///
    531    /// struct Foo(Vec<i32>, Vec<u32>);
    532    ///
    533    /// impl fmt::Debug for Foo {
    534    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    535    ///         fmt.debug_set()
    536    ///            .entry(&self.0) // Adds the first "entry".
    537    ///            .entry(&self.1) // Adds the second "entry".
    538    ///            .finish()
    539    ///     }
    540    /// }
    541    ///
    542    /// assert_eq!(
    543    ///     format!("{:?}", Foo(vec![10, 11], vec![12, 13])),
    544    ///     "{[10, 11], [12, 13]}",
    545    /// );
    546    /// ```
    547    #[stable(feature = "debug_builders", since = "1.2.0")]
    548    pub fn entry(&mut self, entry: &dyn fmt::Debug) -> &mut Self {
    549        self.inner.entry_with(|f| entry.fmt(f));
    550        self
    551    }
    552
    553    /// Adds a new entry to the set output.
    554    ///
    555    /// This method is equivalent to [`DebugSet::entry`], but formats the
    556    /// entry using a provided closure rather than by calling [`Debug::fmt`].
    557    #[unstable(feature = "debug_closure_helpers", issue = "117729")]
    558    pub fn entry_with<F>(&mut self, entry_fmt: F) -> &mut Self
    559    where
    560        F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result,
    561    {
    562        self.inner.entry_with(entry_fmt);
    563        self
    564    }
    565
    566    /// Adds the contents of an iterator of entries to the set output.
    567    ///
    568    /// # Examples
    569    ///
    570    /// ```
    571    /// use std::fmt;
    572    ///
    573    /// struct Foo(Vec<i32>, Vec<u32>);
    574    ///
    575    /// impl fmt::Debug for Foo {
    576    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    577    ///         fmt.debug_set()
    578    ///            .entries(self.0.iter()) // Adds the first "entry".
    579    ///            .entries(self.1.iter()) // Adds the second "entry".
    580    ///            .finish()
    581    ///     }
    582    /// }
    583    ///
    584    /// assert_eq!(
    585    ///     format!("{:?}", Foo(vec![10, 11], vec![12, 13])),
    586    ///     "{10, 11, 12, 13}",
    587    /// );
    588    /// ```
    589    #[stable(feature = "debug_builders", since = "1.2.0")]
    590    pub fn entries<D, I>(&mut self, entries: I) -> &mut Self
    591    where
    592        D: fmt::Debug,
    593        I: IntoIterator<Item = D>,
    594    {
    595        for entry in entries {
    596            self.entry(&entry);
    597        }
    598        self
    599    }
    600
    601    /// Marks the set as non-exhaustive, indicating to the reader that there are some other
    602    /// elements that are not shown in the debug representation.
    603    ///
    604    /// # Examples
    605    ///
    606    /// ```
    607    /// use std::fmt;
    608    ///
    609    /// struct Foo(Vec<i32>);
    610    ///
    611    /// impl fmt::Debug for Foo {
    612    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    613    ///         // Print at most two elements, abbreviate the rest
    614    ///         let mut f = fmt.debug_set();
    615    ///         let mut f = f.entries(self.0.iter().take(2));
    616    ///         if self.0.len() > 2 {
    617    ///             f.finish_non_exhaustive()
    618    ///         } else {
    619    ///             f.finish()
    620    ///         }
    621    ///     }
    622    /// }
    623    ///
    624    /// assert_eq!(
    625    ///     format!("{:?}", Foo(vec![1, 2, 3, 4])),
    626    ///     "{1, 2, ..}",
    627    /// );
    628    /// ```
    629    #[stable(feature = "debug_more_non_exhaustive", since = "1.83.0")]
    630    pub fn finish_non_exhaustive(&mut self) -> fmt::Result {
    631        self.inner.result = self.inner.result.and_then(|_| {
    632            if self.inner.has_fields {
    633                if self.inner.is_pretty() {
    634                    let mut slot = None;
    635                    let mut state = Default::default();
    636                    let mut writer = PadAdapter::wrap(self.inner.fmt, &mut slot, &mut state);
    637                    writer.write_str("..\n")?;
    638                    self.inner.fmt.write_str("}")
    639                } else {
    640                    self.inner.fmt.write_str(", ..}")
    641                }
    642            } else {
    643                self.inner.fmt.write_str("..}")
    644            }
    645        });
    646        self.inner.result
    647    }
    648
    649    /// Finishes output and returns any error encountered.
    650    ///
    651    /// # Examples
    652    ///
    653    /// ```
    654    /// use std::fmt;
    655    ///
    656    /// struct Foo(Vec<i32>);
    657    ///
    658    /// impl fmt::Debug for Foo {
    659    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    660    ///         fmt.debug_set()
    661    ///            .entries(self.0.iter())
    662    ///            .finish() // Ends the set formatting.
    663    ///     }
    664    /// }
    665    ///
    666    /// assert_eq!(
    667    ///     format!("{:?}", Foo(vec![10, 11])),
    668    ///     "{10, 11}",
    669    /// );
    670    /// ```
    671    #[stable(feature = "debug_builders", since = "1.2.0")]
    672    pub fn finish(&mut self) -> fmt::Result {
    673        self.inner.result = self.inner.result.and_then(|_| self.inner.fmt.write_str("}"));
    674        self.inner.result
    675    }
    676}
    677
    678/// A struct to help with [`fmt::Debug`](Debug) implementations.
    679///
    680/// This is useful when you wish to output a formatted list of items as a part
    681/// of your [`Debug::fmt`] implementation.
    682///
    683/// This can be constructed by the [`Formatter::debug_list`] method.
    684///
    685/// # Examples
    686///
    687/// ```
    688/// use std::fmt;
    689///
    690/// struct Foo(Vec<i32>);
    691///
    692/// impl fmt::Debug for Foo {
    693///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    694///         fmt.debug_list().entries(self.0.iter()).finish()
    695///     }
    696/// }
    697///
    698/// assert_eq!(
    699///     format!("{:?}", Foo(vec![10, 11])),
    700///     "[10, 11]",
    701/// );
    702/// ```
    703#[must_use = "must eventually call `finish()` on Debug builders"]
    704#[allow(missing_debug_implementations)]
    705#[stable(feature = "debug_builders", since = "1.2.0")]
    706pub struct DebugList<'a, 'b: 'a> {
    707    inner: DebugInner<'a, 'b>,
    708}
    709
    710pub(super) fn debug_list_new<'a, 'b>(fmt: &'a mut fmt::Formatter<'b>) -> DebugList<'a, 'b> {
    711    let result = fmt.write_str("[");
    712    DebugList { inner: DebugInner { fmt, result, has_fields: false } }
    713}
    714
    715impl<'a, 'b: 'a> DebugList<'a, 'b> {
    716    /// Adds a new entry to the list output.
    717    ///
    718    /// # Examples
    719    ///
    720    /// ```
    721    /// use std::fmt;
    722    ///
    723    /// struct Foo(Vec<i32>, Vec<u32>);
    724    ///
    725    /// impl fmt::Debug for Foo {
    726    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    727    ///         fmt.debug_list()
    728    ///            .entry(&self.0) // We add the first "entry".
    729    ///            .entry(&self.1) // We add the second "entry".
    730    ///            .finish()
    731    ///     }
    732    /// }
    733    ///
    734    /// assert_eq!(
    735    ///     format!("{:?}", Foo(vec![10, 11], vec![12, 13])),
    736    ///     "[[10, 11], [12, 13]]",
    737    /// );
    738    /// ```
    739    #[stable(feature = "debug_builders", since = "1.2.0")]
    740    pub fn entry(&mut self, entry: &dyn fmt::Debug) -> &mut Self {
    741        self.inner.entry_with(|f| entry.fmt(f));
    742        self
    743    }
    744
    745    /// Adds a new entry to the list output.
    746    ///
    747    /// This method is equivalent to [`DebugList::entry`], but formats the
    748    /// entry using a provided closure rather than by calling [`Debug::fmt`].
    749    #[unstable(feature = "debug_closure_helpers", issue = "117729")]
    750    pub fn entry_with<F>(&mut self, entry_fmt: F) -> &mut Self
    751    where
    752        F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result,
    753    {
    754        self.inner.entry_with(entry_fmt);
    755        self
    756    }
    757
    758    /// Adds the contents of an iterator of entries to the list output.
    759    ///
    760    /// # Examples
    761    ///
    762    /// ```
    763    /// use std::fmt;
    764    ///
    765    /// struct Foo(Vec<i32>, Vec<u32>);
    766    ///
    767    /// impl fmt::Debug for Foo {
    768    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    769    ///         fmt.debug_list()
    770    ///            .entries(self.0.iter())
    771    ///            .entries(self.1.iter())
    772    ///            .finish()
    773    ///     }
    774    /// }
    775    ///
    776    /// assert_eq!(
    777    ///     format!("{:?}", Foo(vec![10, 11], vec![12, 13])),
    778    ///     "[10, 11, 12, 13]",
    779    /// );
    780    /// ```
    781    #[stable(feature = "debug_builders", since = "1.2.0")]
    782    pub fn entries<D, I>(&mut self, entries: I) -> &mut Self
    783    where
    784        D: fmt::Debug,
    785        I: IntoIterator<Item = D>,
    786    {
    787        for entry in entries {
    788            self.entry(&entry);
    789        }
    790        self
    791    }
    792
    793    /// Marks the list as non-exhaustive, indicating to the reader that there are some other
    794    /// elements that are not shown in the debug representation.
    795    ///
    796    /// # Examples
    797    ///
    798    /// ```
    799    /// use std::fmt;
    800    ///
    801    /// struct Foo(Vec<i32>);
    802    ///
    803    /// impl fmt::Debug for Foo {
    804    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    805    ///         // Print at most two elements, abbreviate the rest
    806    ///         let mut f = fmt.debug_list();
    807    ///         let mut f = f.entries(self.0.iter().take(2));
    808    ///         if self.0.len() > 2 {
    809    ///             f.finish_non_exhaustive()
    810    ///         } else {
    811    ///             f.finish()
    812    ///         }
    813    ///     }
    814    /// }
    815    ///
    816    /// assert_eq!(
    817    ///     format!("{:?}", Foo(vec![1, 2, 3, 4])),
    818    ///     "[1, 2, ..]",
    819    /// );
    820    /// ```
    821    #[stable(feature = "debug_more_non_exhaustive", since = "1.83.0")]
    822    pub fn finish_non_exhaustive(&mut self) -> fmt::Result {
    823        self.inner.result.and_then(|_| {
    824            if self.inner.has_fields {
    825                if self.inner.is_pretty() {
    826                    let mut slot = None;
    827                    let mut state = Default::default();
    828                    let mut writer = PadAdapter::wrap(self.inner.fmt, &mut slot, &mut state);
    829                    writer.write_str("..\n")?;
    830                    self.inner.fmt.write_str("]")
    831                } else {
    832                    self.inner.fmt.write_str(", ..]")
    833                }
    834            } else {
    835                self.inner.fmt.write_str("..]")
    836            }
    837        })
    838    }
    839
    840    /// Finishes output and returns any error encountered.
    841    ///
    842    /// # Examples
    843    ///
    844    /// ```
    845    /// use std::fmt;
    846    ///
    847    /// struct Foo(Vec<i32>);
    848    ///
    849    /// impl fmt::Debug for Foo {
    850    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    851    ///         fmt.debug_list()
    852    ///            .entries(self.0.iter())
    853    ///            .finish() // Ends the list formatting.
    854    ///     }
    855    /// }
    856    ///
    857    /// assert_eq!(
    858    ///     format!("{:?}", Foo(vec![10, 11])),
    859    ///     "[10, 11]",
    860    /// );
    861    /// ```
    862    #[stable(feature = "debug_builders", since = "1.2.0")]
    863    pub fn finish(&mut self) -> fmt::Result {
    864        self.inner.result = self.inner.result.and_then(|_| self.inner.fmt.write_str("]"));
    865        self.inner.result
    866    }
    867}
    868
    869/// A struct to help with [`fmt::Debug`](Debug) implementations.
    870///
    871/// This is useful when you wish to output a formatted map as a part of your
    872/// [`Debug::fmt`] implementation.
    873///
    874/// This can be constructed by the [`Formatter::debug_map`] method.
    875///
    876/// # Examples
    877///
    878/// ```
    879/// use std::fmt;
    880///
    881/// struct Foo(Vec<(String, i32)>);
    882///
    883/// impl fmt::Debug for Foo {
    884///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    885///         fmt.debug_map().entries(self.0.iter().map(|&(ref k, ref v)| (k, v))).finish()
    886///     }
    887/// }
    888///
    889/// assert_eq!(
    890///     format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    891///     r#"{"A": 10, "B": 11}"#,
    892/// );
    893/// ```
    894#[must_use = "must eventually call `finish()` on Debug builders"]
    895#[allow(missing_debug_implementations)]
    896#[stable(feature = "debug_builders", since = "1.2.0")]
    897pub struct DebugMap<'a, 'b: 'a> {
    898    fmt: &'a mut fmt::Formatter<'b>,
    899    result: fmt::Result,
    900    has_fields: bool,
    901    has_key: bool,
    902    // The state of newlines is tracked between keys and values
    903    state: PadAdapterState,
    904}
    905
    906pub(super) fn debug_map_new<'a, 'b>(fmt: &'a mut fmt::Formatter<'b>) -> DebugMap<'a, 'b> {
    907    let result = fmt.write_str("{");
    908    DebugMap { fmt, result, has_fields: false, has_key: false, state: Default::default() }
    909}
    910
    911impl<'a, 'b: 'a> DebugMap<'a, 'b> {
    912    /// Adds a new entry to the map output.
    913    ///
    914    /// # Examples
    915    ///
    916    /// ```
    917    /// use std::fmt;
    918    ///
    919    /// struct Foo(Vec<(String, i32)>);
    920    ///
    921    /// impl fmt::Debug for Foo {
    922    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    923    ///         fmt.debug_map()
    924    ///            .entry(&"whole", &self.0) // We add the "whole" entry.
    925    ///            .finish()
    926    ///     }
    927    /// }
    928    ///
    929    /// assert_eq!(
    930    ///     format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    931    ///     r#"{"whole": [("A", 10), ("B", 11)]}"#,
    932    /// );
    933    /// ```
    934    #[stable(feature = "debug_builders", since = "1.2.0")]
    935    pub fn entry(&mut self, key: &dyn fmt::Debug, value: &dyn fmt::Debug) -> &mut Self {
    936        self.key(key).value(value)
    937    }
    938
    939    /// Adds the key part of a new entry to the map output.
    940    ///
    941    /// This method, together with `value`, is an alternative to `entry` that
    942    /// can be used when the complete entry isn't known upfront. Prefer the `entry`
    943    /// method when it's possible to use.
    944    ///
    945    /// # Panics
    946    ///
    947    /// `key` must be called before `value` and each call to `key` must be followed
    948    /// by a corresponding call to `value`. Otherwise this method will panic.
    949    ///
    950    /// # Examples
    951    ///
    952    /// ```
    953    /// use std::fmt;
    954    ///
    955    /// struct Foo(Vec<(String, i32)>);
    956    ///
    957    /// impl fmt::Debug for Foo {
    958    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    959    ///         fmt.debug_map()
    960    ///            .key(&"whole").value(&self.0) // We add the "whole" entry.
    961    ///            .finish()
    962    ///     }
    963    /// }
    964    ///
    965    /// assert_eq!(
    966    ///     format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    967    ///     r#"{"whole": [("A", 10), ("B", 11)]}"#,
    968    /// );
    969    /// ```
    970    #[stable(feature = "debug_map_key_value", since = "1.42.0")]
    971    pub fn key(&mut self, key: &dyn fmt::Debug) -> &mut Self {
    972        self.key_with(|f| key.fmt(f))
    973    }
    974
    975    /// Adds the key part of a new entry to the map output.
    976    ///
    977    /// This method is equivalent to [`DebugMap::key`], but formats the
    978    /// key using a provided closure rather than by calling [`Debug::fmt`].
    979    #[unstable(feature = "debug_closure_helpers", issue = "117729")]
    980    pub fn key_with<F>(&mut self, key_fmt: F) -> &mut Self
    981    where
    982        F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result,
    983    {
    984        self.result = self.result.and_then(|_| {
    985            assert!(
    986                !self.has_key,
    987                "attempted to begin a new map entry \
    988                                    without completing the previous one"
    989            );
    990
    991            if self.is_pretty() {
    992                if !self.has_fields {
    993                    self.fmt.write_str("\n")?;
    994                }
    995                let mut slot = None;
    996                self.state = Default::default();
    997                let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut self.state);
    998                key_fmt(&mut writer)?;
    999                writer.write_str(": ")?;
    1000            } else {
    1001                if self.has_fields {
    1002                    self.fmt.write_str(", ")?
    1003                }
    1004                key_fmt(self.fmt)?;
    1005                self.fmt.write_str(": ")?;
    1006            }
    1007
    1008            self.has_key = true;
    1009            Ok(())
    1010        });
    1011
    1012        self
    1013    }
    1014
    1015    /// Adds the value part of a new entry to the map output.
    1016    ///
    1017    /// This method, together with `key`, is an alternative to `entry` that
    1018    /// can be used when the complete entry isn't known upfront. Prefer the `entry`
    1019    /// method when it's possible to use.
    1020    ///
    1021    /// # Panics
    1022    ///
    1023    /// `key` must be called before `value` and each call to `key` must be followed
    1024    /// by a corresponding call to `value`. Otherwise this method will panic.
    1025    ///
    1026    /// # Examples
    1027    ///
    1028    /// ```
    1029    /// use std::fmt;
    1030    ///
    1031    /// struct Foo(Vec<(String, i32)>);
    1032    ///
    1033    /// impl fmt::Debug for Foo {
    1034    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    1035    ///         fmt.debug_map()
    1036    ///            .key(&"whole").value(&self.0) // We add the "whole" entry.
    1037    ///            .finish()
    1038    ///     }
    1039    /// }
    1040    ///
    1041    /// assert_eq!(
    1042    ///     format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    1043    ///     r#"{"whole": [("A", 10), ("B", 11)]}"#,
    1044    /// );
    1045    /// ```
    1046    #[stable(feature = "debug_map_key_value", since = "1.42.0")]
    1047    pub fn value(&mut self, value: &dyn fmt::Debug) -> &mut Self {
    1048        self.value_with(|f| value.fmt(f))
    1049    }
    1050
    1051    /// Adds the value part of a new entry to the map output.
    1052    ///
    1053    /// This method is equivalent to [`DebugMap::value`], but formats the
    1054    /// value using a provided closure rather than by calling [`Debug::fmt`].
    1055    #[unstable(feature = "debug_closure_helpers", issue = "117729")]
    1056    pub fn value_with<F>(&mut self, value_fmt: F) -> &mut Self
    1057    where
    1058        F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result,
    1059    {
    1060        self.result = self.result.and_then(|_| {
    1061            assert!(self.has_key, "attempted to format a map value before its key");
    1062
    1063            if self.is_pretty() {
    1064                let mut slot = None;
    1065                let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut self.state);
    1066                value_fmt(&mut writer)?;
    1067                writer.write_str(",\n")?;
    1068            } else {
    1069                value_fmt(self.fmt)?;
    1070            }
    1071
    1072            self.has_key = false;
    1073            Ok(())
    1074        });
    1075
    1076        self.has_fields = true;
    1077        self
    1078    }
    1079
    1080    /// Adds the contents of an iterator of entries to the map output.
    1081    ///
    1082    /// # Examples
    1083    ///
    1084    /// ```
    1085    /// use std::fmt;
    1086    ///
    1087    /// struct Foo(Vec<(String, i32)>);
    1088    ///
    1089    /// impl fmt::Debug for Foo {
    1090    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    1091    ///         fmt.debug_map()
    1092    ///            // We map our vec so each entries' first field will become
    1093    ///            // the "key".
    1094    ///            .entries(self.0.iter().map(|&(ref k, ref v)| (k, v)))
    1095    ///            .finish()
    1096    ///     }
    1097    /// }
    1098    ///
    1099    /// assert_eq!(
    1100    ///     format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    1101    ///     r#"{"A": 10, "B": 11}"#,
    1102    /// );
    1103    /// ```
    1104    #[stable(feature = "debug_builders", since = "1.2.0")]
    1105    pub fn entries<K, V, I>(&mut self, entries: I) -> &mut Self
    1106    where
    1107        K: fmt::Debug,
    1108        V: fmt::Debug,
    1109        I: IntoIterator<Item = (K, V)>,
    1110    {
    1111        for (k, v) in entries {
    1112            self.entry(&k, &v);
    1113        }
    1114        self
    1115    }
    1116
    1117    /// Marks the map as non-exhaustive, indicating to the reader that there are some other
    1118    /// entries that are not shown in the debug representation.
    1119    ///
    1120    /// # Examples
    1121    ///
    1122    /// ```
    1123    /// use std::fmt;
    1124    ///
    1125    /// struct Foo(Vec<(String, i32)>);
    1126    ///
    1127    /// impl fmt::Debug for Foo {
    1128    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    1129    ///         // Print at most two elements, abbreviate the rest
    1130    ///         let mut f = fmt.debug_map();
    1131    ///         let mut f = f.entries(self.0.iter().take(2).map(|&(ref k, ref v)| (k, v)));
    1132    ///         if self.0.len() > 2 {
    1133    ///             f.finish_non_exhaustive()
    1134    ///         } else {
    1135    ///             f.finish()
    1136    ///         }
    1137    ///     }
    1138    /// }
    1139    ///
    1140    /// assert_eq!(
    1141    ///     format!("{:?}", Foo(vec![
    1142    ///         ("A".to_string(), 10),
    1143    ///         ("B".to_string(), 11),
    1144    ///         ("C".to_string(), 12),
    1145    ///     ])),
    1146    ///     r#"{"A": 10, "B": 11, ..}"#,
    1147    /// );
    1148    /// ```
    1149    #[stable(feature = "debug_more_non_exhaustive", since = "1.83.0")]
    1150    pub fn finish_non_exhaustive(&mut self) -> fmt::Result {
    1151        self.result = self.result.and_then(|_| {
    1152            assert!(!self.has_key, "attempted to finish a map with a partial entry");
    1153
    1154            if self.has_fields {
    1155                if self.is_pretty() {
    1156                    let mut slot = None;
    1157                    let mut state = Default::default();
    1158                    let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state);
    1159                    writer.write_str("..\n")?;
    1160                    self.fmt.write_str("}")
    1161                } else {
    1162                    self.fmt.write_str(", ..}")
    1163                }
    1164            } else {
    1165                self.fmt.write_str("..}")
    1166            }
    1167        });
    1168        self.result
    1169    }
    1170
    1171    /// Finishes output and returns any error encountered.
    1172    ///
    1173    /// # Panics
    1174    ///
    1175    /// `key` must be called before `value` and each call to `key` must be followed
    1176    /// by a corresponding call to `value`. Otherwise this method will panic.
    1177    ///
    1178    /// # Examples
    1179    ///
    1180    /// ```
    1181    /// use std::fmt;
    1182    ///
    1183    /// struct Foo(Vec<(String, i32)>);
    1184    ///
    1185    /// impl fmt::Debug for Foo {
    1186    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    1187    ///         fmt.debug_map()
    1188    ///            .entries(self.0.iter().map(|&(ref k, ref v)| (k, v)))
    1189    ///            .finish() // Ends the map formatting.
    1190    ///     }
    1191    /// }
    1192    ///
    1193    /// assert_eq!(
    1194    ///     format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    1195    ///     r#"{"A": 10, "B": 11}"#,
    1196    /// );
    1197    /// ```
    1198    #[stable(feature = "debug_builders", since = "1.2.0")]
    1199    pub fn finish(&mut self) -> fmt::Result {
    1200        self.result = self.result.and_then(|_| {
    1201            assert!(!self.has_key, "attempted to finish a map with a partial entry");
    1202
    1203            self.fmt.write_str("}")
    1204        });
    1205        self.result
    1206    }
    1207
    1208    fn is_pretty(&self) -> bool {
    1209        self.fmt.alternate()
    1210    }
    1211}
    1212
    1213/// Creates a type whose [`fmt::Debug`] and [`fmt::Display`] impls are provided with the function
    1214/// `f`.
    1215///
    1216/// # Examples
    1217///
    1218/// ```
    1219/// #![feature(debug_closure_helpers)]
    1220/// use std::fmt;
    1221///
    1222/// let value = 'a';
    1223/// assert_eq!(format!("{}", value), "a");
    1224/// assert_eq!(format!("{:?}", value), "'a'");
    1225///
    1226/// let wrapped = fmt::from_fn(|f| write!(f, "{value:?}"));
    1227/// assert_eq!(format!("{}", wrapped), "'a'");
    1228/// assert_eq!(format!("{:?}", wrapped), "'a'");
    1229/// ```
    1230#[unstable(feature = "debug_closure_helpers", issue = "117729")]
    1231#[must_use = "returns a type implementing Debug and Display, which do not have any effects unless they are used"]
    1232pub fn from_fn<F: Fn(&mut fmt::Formatter<'_>) -> fmt::Result>(f: F) -> FromFn<F> {
    1233    FromFn(f)
    1234}
    1235
    1236/// Implements [`fmt::Debug`] and [`fmt::Display`] using a function.
    1237///
    1238/// Created with [`from_fn`].
    1239#[unstable(feature = "debug_closure_helpers", issue = "117729")]
    1240pub struct FromFn<F>(F)
    1241where
    1242    F: Fn(&mut fmt::Formatter<'_>) -> fmt::Result;
    1243
    1244#[unstable(feature = "debug_closure_helpers", issue = "117729")]
    1245impl<F> fmt::Debug for FromFn<F>
    1246where
    1247    F: Fn(&mut fmt::Formatter<'_>) -> fmt::Result,
    1248{
    1249    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    1250        (self.0)(f)
    1251    }
    1252}
    1253
    1254#[unstable(feature = "debug_closure_helpers", issue = "117729")]
    1255impl<F> fmt::Display for FromFn<F>
    1256where
    1257    F: Fn(&mut fmt::Formatter<'_>) -> fmt::Result,
    1258{
    1259    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    1260        (self.0)(f)
    1261    }
    1262}