//! 用于格式化和打印字符串的实用工具。

#![stable(feature = "rust1", since = "1.0.0")]

use crate::cell::{Cell, Ref, RefCell, RefMut, SyncUnsafeCell, UnsafeCell};
use crate::char::EscapeDebugExtArgs;
use crate::iter;
use crate::marker::PhantomData;
use crate::mem;
use crate::num::fmt as numfmt;
use crate::ops::Deref;
use crate::result;
use crate::str;

mod builders;
#[cfg(not(no_fp_fmt_parse))]
mod float;
#[cfg(no_fp_fmt_parse)]
mod nofloat;
mod num;
mod rt;

#[stable(feature = "fmt_flags_align", since = "1.28.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "Alignment")]
/// `Formatter::align` 返回的可能的对齐方式
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum Alignment {
    #[stable(feature = "fmt_flags_align", since = "1.28.0")]
    /// 指示内容应左对齐。
    Left,
    #[stable(feature = "fmt_flags_align", since = "1.28.0")]
    /// 指示内容应右对齐。
    Right,
    #[stable(feature = "fmt_flags_align", since = "1.28.0")]
    /// 指示内容应居中对齐。
    Center,
}

#[stable(feature = "debug_builders", since = "1.2.0")]
pub use self::builders::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple};

/// 格式化程序方法返回的类型。
///
/// # Examples
///
/// ```
/// use std::fmt;
///
/// #[derive(Debug)]
/// struct Triangle {
///     a: f32,
///     b: f32,
///     c: f32
/// }
///
/// impl fmt::Display for Triangle {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         write!(f, "({}, {}, {})", self.a, self.b, self.c)
///     }
/// }
///
/// let pythagorean_triple = Triangle { a: 3.0, b: 4.0, c: 5.0 };
///
/// assert_eq!(format!("{pythagorean_triple}"), "(3, 4, 5)");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub type Result = result::Result<(), Error>;

/// 将消息格式化为流后返回的错误类型。
///
/// 除了发生错误以外，此类型不支持错误的传输。
/// 必须安排任何其他信息以通过其他方式进行传输。
///
/// 要记住的重要一点是，不要将 `fmt::Error` 类型与 [`std::io::Error`] 或 [`std::error::Error`] 混淆，在作用域中也可以将它们与 [`std::io::Error`] 或 [`std::error::Error`] 混淆。
///
///
/// [`std::io::Error`]: ../../std/io/struct.Error.html
/// [`std::error::Error`]: ../../std/error/trait.Error.html
///
/// # Examples
///
/// ```rust
/// use std::fmt::{self, write};
///
/// let mut output = String::new();
/// if let Err(fmt::Error) = write(&mut output, format_args!("Hello {}!", "world")) {
///     panic!("An error occurred");
/// }
/// ```
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Copy, Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct Error;

/// 一个用于写入或格式化为 Unicode 接受的缓冲区或流的 trait。
///
/// 一个只接受 UTF-8 编码的数据，而不是 [flushable] 的 trait。
/// 如果您只想接受 Unicode 且不需要冲洗，则应实现此 trait; 否则，请执行此操作。
/// 否则，您应该实现 [`std::io::Write`]。
///
/// [`std::io::Write`]: ../../std/io/trait.Write.html
/// [flushable]: ../../std/io/trait.Write.html#tymethod.flush
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Write {
    /// 将字符串切片写入此 writer，返回写入是否成功。
    ///
    /// 仅当成功写入整个字符串切片后，此方法才能成功，并且只有在写入所有数据或发生错误后，该方法才会返回。
    ///
    /// # Errors
    ///
    /// 错误时，此函数将返回 [`Error`] 的实例。
    ///
    /// std::fmt::Error 的目的是在底层目的地遇到一些错误阻止它接受更多文本时中止格式化操作; 通常应该传播而不是处理它，至少在实现格式化 traits 时。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt::{Error, Write};
    ///
    /// fn writer<W: Write>(f: &mut W, s: &str) -> Result<(), Error> {
    ///     f.write_str(s)
    /// }
    ///
    /// let mut buf = String::new();
    /// writer(&mut buf, "hola").unwrap();
    /// assert_eq!(&buf, "hola");
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn write_str(&mut self, s: &str) -> Result;

    /// 将 [`char`] 写入此 writer，返回写入是否成功。
    ///
    /// 单个 [`char`] 可以被编码为一个以上的字节。
    /// 仅当成功写入了整个字节序列后，此方法才能成功，并且直到所有数据都已写入或发生错误后，该方法才会返回。
    ///
    ///
    /// # Errors
    ///
    /// 错误时，此函数将返回 [`Error`] 的实例。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt::{Error, Write};
    ///
    /// fn writer<W: Write>(f: &mut W, c: char) -> Result<(), Error> {
    ///     f.write_char(c)
    /// }
    ///
    /// let mut buf = String::new();
    /// writer(&mut buf, 'a').unwrap();
    /// writer(&mut buf, 'b').unwrap();
    /// assert_eq!(&buf, "ab");
    /// ```
    ///
    #[stable(feature = "fmt_write_char", since = "1.1.0")]
    fn write_char(&mut self, c: char) -> Result {
        self.write_str(c.encode_utf8(&mut [0; 4]))
    }

    /// 结合使用 [`write!`] 宏和 trait 的实现者。
    ///
    /// 通常不应手动调用此方法，而应通过 [`write!`] 宏本身来调用。
    ///
    ///
    /// # Errors
    ///
    /// 错误时，此函数将返回 [`Error`] 的实例。
    /// 详情请参见 [write_str](Write::write_str)。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt::{Error, Write};
    ///
    /// fn writer<W: Write>(f: &mut W, s: &str) -> Result<(), Error> {
    ///     f.write_fmt(format_args!("{s}"))
    /// }
    ///
    /// let mut buf = String::new();
    /// writer(&mut buf, "world").unwrap();
    /// assert_eq!(&buf, "world");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    fn write_fmt(mut self: &mut Self, args: Arguments<'_>) -> Result {
        write(&mut self, args)
    }
}

#[stable(feature = "fmt_write_blanket_impl", since = "1.4.0")]
impl<W: Write + ?Sized> Write for &mut W {
    fn write_str(&mut self, s: &str) -> Result {
        (**self).write_str(s)
    }

    fn write_char(&mut self, c: char) -> Result {
        (**self).write_char(c)
    }

    fn write_fmt(&mut self, args: Arguments<'_>) -> Result {
        (**self).write_fmt(args)
    }
}

/// 格式化配置。
///
/// `Formatter` 代表与格式相关的各种选项。
/// 用户不直接构建 `Formatter`s。将所有格式为 traits 的 `fmt` 方法 (例如 [`Debug`] 和 [`Display`]) 传递给 `fmt` 方法。
///
///
/// 要与 `Formatter` 进行交互，您将调用各种方法来更改与格式相关的各种选项。
/// 有关示例，请参见下面在 `Formatter` 上定义的方法的文档。
///
#[allow(missing_debug_implementations)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Formatter<'a> {
    flags: u32,
    fill: char,
    align: rt::Alignment,
    width: Option<usize>,
    precision: Option<usize>,

    buf: &'a mut (dyn Write + 'a),
}

impl<'a> Formatter<'a> {
    /// 使用默认设置创建一个新的格式化程序。
    ///
    /// 在不需要完整的 `Arguments` 结构 (由 `format_args!` 创建) 的情况下，这可以用作微优化； 在简单的格式化场景中使用 `Arguments` 的使用成本稍高一些。
    ///
    ///
    /// 目前不打算在标准库之外使用。
    ///
    #[unstable(feature = "fmt_internals", reason = "internal to standard library", issue = "none")]
    #[doc(hidden)]
    pub fn new(buf: &'a mut (dyn Write + 'a)) -> Formatter<'a> {
        Formatter {
            flags: 0,
            fill: ' ',
            align: rt::Alignment::Unknown,
            width: None,
            precision: None,
            buf,
        }
    }
}

/// 该结构体表示格式字符串及其参数的安全预编译版本。
/// 由于无法安全地完成此操作，因此无法在运行时生成该文件，因此未提供任何构造函数，并且该字段为私有字段以防止修改。
///
///
/// [`format_args!`] 宏将安全地创建此结构体的实例。
/// 宏在编译时验证格式字符串，因此可以安全地执行 [`write()`] 和 [`format()`] 函数的使用。
///
/// 您可以在 `Debug` 和 `Display` 上下文中使用 [`format_args!`] 返回的 `Arguments<'a>`，如下所示。
/// 该示例还显示 `Debug` 和 `Display` 的格式相同: `format_args!` 中的插值格式字符串。
///
/// ```rust
/// let debug = format!("{:?}", format_args!("{} foo {:?}", 1, 2));
/// let display = format!("{}", format_args!("{} foo {:?}", 1, 2));
/// assert_eq!("1 foo 2", display);
/// assert_eq!(display, debug);
/// ```
///
/// [`format()`]: ../../std/fmt/fn.format.html
///
///
///
///
#[lang = "format_arguments"]
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Copy, Clone)]
pub struct Arguments<'a> {
    // 格式化要打印的字符串。
    pieces: &'a [&'static str],

    // 占位符规范，如果所有规范均为默认规范，则为 `None` (与 "{}{}" 相同)。
    fmt: Option<&'a [rt::Placeholder]>,

    // 用于插值的动态参数，与字符串切片交织。
    // (每个参数前面都有一个字符串。)
    args: &'a [rt::Argument<'a>],
}

/// 由 format_args!() 宏用于创建 fmt::Arguments 对象。
#[doc(hidden)]
#[unstable(feature = "fmt_internals", issue = "none")]
impl<'a> Arguments<'a> {
    #[inline]
    #[rustc_const_unstable(feature = "const_fmt_arguments_new", issue = "none")]
    pub const fn new_const(pieces: &'a [&'static str]) -> Self {
        if pieces.len() > 1 {
            panic!("invalid args");
        }
        Arguments { pieces, fmt: None, args: &[] }
    }

    /// 当使用 format_args! () 宏时，此函数用于生成参数结构体。
    ///
    #[inline]
    pub fn new_v1(pieces: &'a [&'static str], args: &'a [rt::Argument<'a>]) -> Arguments<'a> {
        if pieces.len() < args.len() || pieces.len() > args.len() + 1 {
            panic!("invalid args");
        }
        Arguments { pieces, fmt: None, args }
    }

    /// 此函数用于指定非标准格式设置参数。
    ///
    /// `rt::UnsafeArg` 是必需的，因为必须保持以下不，变体，才能使此功能安全:
    ///
    /// 1. `pieces` 必须至少与 `fmt` 一样长。
    /// 2. `fmt` 中的每个 `rt::Placeholder::position` 值都必须是 `args` 的有效索引。
    /// 3. `fmt` 中的每个 `rt::Count::Param` 都必须包含 `args` 的有效索引。
    #[inline]
    pub fn new_v1_formatted(
        pieces: &'a [&'static str],
        args: &'a [rt::Argument<'a>],
        fmt: &'a [rt::Placeholder],
        _unsafe_arg: rt::UnsafeArg,
    ) -> Arguments<'a> {
        Arguments { pieces, fmt: Some(fmt), args }
    }

    /// 估计格式化文本的长度。
    ///
    /// 当使用 `format!` 时，这旨在用于设置 `String` 的初始容量。
    /// Note: 这既不是下限也不是上限。
    #[inline]
    pub fn estimated_capacity(&self) -> usize {
        let pieces_length: usize = self.pieces.iter().map(|x| x.len()).sum();

        if self.args.is_empty() {
            pieces_length
        } else if !self.pieces.is_empty() && self.pieces[0].is_empty() && pieces_length < 16 {
            // 如果格式字符串以参数开头，则不要预分配任何内容，除非片段长度很大。
            //
            //
            0
        } else {
            // 有一些参数，因此任何其他推送都会重新分配字符串。
            //
            // 为避免这种情况，我们将此处的容量设置为 "pre-doubling"。
            pieces_length.checked_mul(2).unwrap_or(0)
        }
    }
}

impl<'a> Arguments<'a> {
    /// 获取格式化后的字符串，如果它没有要在运行时格式化的参数。
    ///
    /// 在某些情况下，这可用于避免分配。
    ///
    /// # Guarantees
    ///
    /// 对于 `format_args!("just a literal")`，这个函数保证返回 `Some("just a literal")`。
    ///
    /// 对于大多数带有占位符的情况，这个函数将返回 `None`。
    ///
    /// 但是，编译器可能会执行优化，即使格式字符串包含占位符，也会导致此函数返回 `Some(_)`。
    /// 例如，`format_args!("Hello, {}!", "world")` 可能被优化为 `format_args!("Hello, world!")`，这样 `as_str()` 返回 `Some("Hello, world!")`。
    ///
    ///
    /// 除了微不足道的情况 (没有占位符) 之外的任何行为都不能得到保证，并且除了优化之外不应依赖于任何其他行为。
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::fmt::Arguments;
    ///
    /// fn write_str(_: &str) { /* ... */ }
    ///
    /// fn write_fmt(args: &Arguments<'_>) {
    ///     if let Some(s) = args.as_str() {
    ///         write_str(s)
    ///     } else {
    ///         write_str(&args.to_string());
    ///     }
    /// }
    /// ```
    ///
    /// ```rust
    /// assert_eq!(format_args!("hello").as_str(), Some("hello"));
    /// assert_eq!(format_args!("").as_str(), Some(""));
    /// assert_eq!(format_args!("{:?}", std::env::current_dir()).as_str(), None);
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "fmt_as_str", since = "1.52.0")]
    #[rustc_const_unstable(feature = "const_arguments_as_str", issue = "103900")]
    #[must_use]
    #[inline]
    pub const fn as_str(&self) -> Option<&'static str> {
        match (self.pieces, self.args) {
            ([], []) => Some(""),
            ([s], []) => Some(s),
            _ => None,
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Debug for Arguments<'_> {
    fn fmt(&self, fmt: &mut Formatter<'_>) -> Result {
        Display::fmt(self, fmt)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Display for Arguments<'_> {
    fn fmt(&self, fmt: &mut Formatter<'_>) -> Result {
        write(fmt.buf, *self)
    }
}

/// `?` 格式。
///
/// `Debug` 应该在面向程序员的调试上下文中格式化输出。
///
/// 一般来说，您应该只将 `derive` 和 `Debug` 实现。
///
/// 当与备用格式说明符 `#?` 一起使用时，输出将被漂亮地打印。
///
/// 有关格式化程序的更多信息，请参见 [模块级文档][module]。
///
/// [module]: ../../std/fmt/index.html
///
/// 如果所有字段都实现 `Debug`，则此 trait 可以与 `#[derive]` 一起使用。当为结构体 `derived' 时，它将使用 `struct` 的名称，然后是 `{`，然后是每个字段名称和 `Debug` 值的逗号分隔列表，然后是 `}`。
/// 对于 `enum`，它将使用变体的名称，如果适用，将使用 `(`，然后是字段的 `Debug` 值，然后是 `)`。
///
/// # Stability
///
/// 派生的 `Debug` 格式不稳定，因此 future Rust 版本可能会更改。此外，标准库 (`std`、`core`、`alloc` 等) 提供的类型的 `Debug` 实现并不稳定，并且也可能随着 future Rust 版本而改变。
///
/// # Examples
///
/// 派生实现：
///
/// ```
/// #[derive(Debug)]
/// struct Point {
///     x: i32,
///     y: i32,
/// }
///
/// let origin = Point { x: 0, y: 0 };
///
/// assert_eq!(format!("The origin is: {origin:?}"), "The origin is: Point { x: 0, y: 0 }");
/// ```
///
/// 手动实现：
///
/// ```
/// use std::fmt;
///
/// struct Point {
///     x: i32,
///     y: i32,
/// }
///
/// impl fmt::Debug for Point {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         f.debug_struct("Point")
///          .field("x", &self.x)
///          .field("y", &self.y)
///          .finish()
///     }
/// }
///
/// let origin = Point { x: 0, y: 0 };
///
/// assert_eq!(format!("The origin is: {origin:?}"), "The origin is: Point { x: 0, y: 0 }");
/// ```
///
/// [`Formatter`] 结构体上有许多辅助方法可以帮助您实现手动实现，例如 [`debug_struct`]。
///
/// [`debug_struct`]: Formatter::debug_struct
///
/// 不希望使用 `Formatter` trait 提供的标准调试表示套件 (`debug_struct`、`debug_tuple`、`debug_list`、`debug_set`、`debug_map`) 的类型可以通过手动向 `Formatter` 写入任意表示来完成完全自定义的操作。
///
///
/// ```
/// # use std::fmt;
/// # struct Point {
/// #     x: i32,
/// #     y: i32,
/// # }
/// #
/// impl fmt::Debug for Point {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         write!(f, "Point [{} {}]", self.x, self.y)
///     }
/// }
/// ```
///
/// 使用 `derive` 或 [`Formatter`] 上的调试构建器 API 的 `Debug` 实现支持使用备用标志 `{:#?}` 的漂亮打印。
///
/// 使用 `#?` 进行漂亮的打印：
///
/// ```
/// #[derive(Debug)]
/// struct Point {
///     x: i32,
///     y: i32,
/// }
///
/// let origin = Point { x: 0, y: 0 };
///
/// assert_eq!(format!("The origin is: {origin:#?}"),
/// "The origin is: Point {
///     x: 0,
///     y: 0,
/// }");
/// ```
///
///
///
///
///
///
///
///
///
///

#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_on_unimplemented(
    on(
        crate_local,
        label = "`{Self}` cannot be formatted using `{{:?}}`",
        note = "add `#[derive(Debug)]` to `{Self}` or manually `impl {Debug} for {Self}`"
    ),
    message = "`{Self}` doesn't implement `{Debug}`",
    label = "`{Self}` cannot be formatted using `{{:?}}` because it doesn't implement `{Debug}`"
)]
#[doc(alias = "{:?}")]
#[rustc_diagnostic_item = "Debug"]
#[rustc_trivial_field_reads]
pub trait Debug {
    /// 使用给定的格式化程序格式化该值。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Position {
    ///     longitude: f32,
    ///     latitude: f32,
    /// }
    ///
    /// impl fmt::Debug for Position {
    ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         f.debug_tuple("")
    ///          .field(&self.longitude)
    ///          .field(&self.latitude)
    ///          .finish()
    ///     }
    /// }
    ///
    /// let position = Position { longitude: 1.987, latitude: 2.983 };
    /// assert_eq!(format!("{position:?}"), "(1.987, 2.983)");
    ///
    /// assert_eq!(format!("{position:#?}"), "(
    ///     1.987,
    ///     2.983,
    /// )");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

// 单独的模块，用于从 prelude 重导出 `Debug` 宏，而无需 `Debug` trait。
pub(crate) mod macros {
    /// 派生宏，生成 `Debug` trait 的 impl。
    #[rustc_builtin_macro]
    #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
    #[allow_internal_unstable(core_intrinsics, fmt_helpers_for_derive)]
    pub macro Debug($item:item) {
        /* compiler built-in */
    }
}
#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[doc(inline)]
pub use macros::Debug;

/// 空格式的格式 trait，`{}`。
///
/// 为一个类型实现这个 trait 将自动为该类型实现 [`ToString`][tostring] trait，允许使用 [`.to_string()`][tostring_function] 方法。
/// 更喜欢为一个类型实现 `Display` trait，而不是 [`ToString`][tostring]。
///
/// `Display` 与 [`Debug`] 类似，但 `Display` 是面向用户的输出，因此无法导出。
///
/// 有关格式化程序的更多信息，请参见 [模块级文档][module]。
///
/// [module]: ../../std/fmt/index.html
/// [tostring]: ../../std/string/trait.ToString.html
/// [tostring_function]: ../../std/string/trait.ToString.html#tymethod.to_string
///
/// # Examples
///
/// 在类型上实现 `Display`：
///
/// ```
/// use std::fmt;
///
/// struct Point {
///     x: i32,
///     y: i32,
/// }
///
/// impl fmt::Display for Point {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         write!(f, "({}, {})", self.x, self.y)
///     }
/// }
///
/// let origin = Point { x: 0, y: 0 };
///
/// assert_eq!(format!("The origin is: {origin}"), "The origin is: (0, 0)");
/// ```
///
///
///
#[rustc_on_unimplemented(
    on(
        any(_Self = "std::path::Path", _Self = "std::path::PathBuf"),
        label = "`{Self}` cannot be formatted with the default formatter; call `.display()` on it",
        note = "call `.display()` or `.to_string_lossy()` to safely print paths, \
                as they may contain non-Unicode data"
    ),
    message = "`{Self}` doesn't implement `{Display}`",
    label = "`{Self}` cannot be formatted with the default formatter",
    note = "in format strings you may be able to use `{{:?}}` (or {{:#?}} for pretty-print) instead"
)]
#[doc(alias = "{}")]
#[rustc_diagnostic_item = "Display"]
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Display {
    /// 使用给定的格式化程序格式化该值。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Position {
    ///     longitude: f32,
    ///     latitude: f32,
    /// }
    ///
    /// impl fmt::Display for Position {
    ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         write!(f, "({}, {})", self.longitude, self.latitude)
    ///     }
    /// }
    ///
    /// assert_eq!("(1.987, 2.983)",
    ///            format!("{}", Position { longitude: 1.987, latitude: 2.983, }));
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

/// `o` 格式。
///
/// `Octal` trait 应该将其输出格式化为 base-8 中的数字。
///
/// 对于原始有符号整数 (`i8` 至 `i128` 和 `isize`)，负值的格式设置为二进制补码表示形式。
///
///
/// 备用标志 `#` 在输出前面添加 `0o`。
///
/// 有关格式化程序的更多信息，请参见 [模块级文档][module]。
///
/// [module]: ../../std/fmt/index.html
///
/// # Examples
///
/// `i32` 的基本用法：
///
/// ```
/// let x = 42; // 42 是八进制的 '52'
///
/// assert_eq!(format!("{x:o}"), "52");
/// assert_eq!(format!("{x:#o}"), "0o52");
///
/// assert_eq!(format!("{:o}", -16), "37777777760");
/// ```
///
/// 在类型上实现 `Octal`：
///
/// ```
/// use std::fmt;
///
/// struct Length(i32);
///
/// impl fmt::Octal for Length {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         let val = self.0;
///
///         fmt::Octal::fmt(&val, f) // 委托给 i32 的实现
///     }
/// }
///
/// let l = Length(9);
///
/// assert_eq!(format!("l as octal is: {l:o}"), "l as octal is: 11");
///
/// assert_eq!(format!("l as octal is: {l:#06o}"), "l as octal is: 0o0011");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Octal {
    /// 使用给定的格式化程序格式化该值。
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

/// `b` 格式。
///
/// `Binary` trait 应该将其输出格式化为二进制格式的数字。
///
/// 对于原始有符号整数 ([`i8`] 至 [`i128`] 和 [`isize`])，负值的格式设置为二进制补码表示形式。
///
///
/// 备用标志 `#` 在输出前面添加 `0b`。
///
/// 有关格式化程序的更多信息，请参见 [模块级文档][module]。
///
/// [module]: ../../std/fmt/index.html
///
/// # Examples
///
/// [`i32`] 的基本用法：
///
/// ```
/// let x = 42; // 42 是 '101010' 二进制
///
/// assert_eq!(format!("{x:b}"), "101010");
/// assert_eq!(format!("{x:#b}"), "0b101010");
///
/// assert_eq!(format!("{:b}", -16), "11111111111111111111111111110000");
/// ```
///
/// 在类型上实现 `Binary`：
///
/// ```
/// use std::fmt;
///
/// struct Length(i32);
///
/// impl fmt::Binary for Length {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         let val = self.0;
///
///         fmt::Binary::fmt(&val, f) // 委托给 i32 的实现
///     }
/// }
///
/// let l = Length(107);
///
/// assert_eq!(format!("l as binary is: {l:b}"), "l as binary is: 1101011");
///
/// assert_eq!(
///     format!("l as binary is: {l:#032b}"),
///     "l as binary is: 0b000000000000000000000001101011"
/// );
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Binary {
    /// 使用给定的格式化程序格式化该值。
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

/// `x` 格式。
///
/// `LowerHex` trait 应该将其输出格式设置为十六进制数字，其中 `a` 至 `f` 为小写形式。
///
/// 对于原始有符号整数 (`i8` 至 `i128` 和 `isize`)，负值的格式设置为二进制补码表示形式。
///
///
/// 备用标志 `#` 在输出前面添加 `0x`。
///
/// 有关格式化程序的更多信息，请参见 [模块级文档][module]。
///
/// [module]: ../../std/fmt/index.html
///
/// # Examples
///
/// `i32` 的基本用法：
///
/// ```
/// let x = 42; // 42 是十六进制的 '2a'
///
/// assert_eq!(format!("{x:x}"), "2a");
/// assert_eq!(format!("{x:#x}"), "0x2a");
///
/// assert_eq!(format!("{:x}", -16), "fffffff0");
/// ```
///
/// 在类型上实现 `LowerHex`：
///
/// ```
/// use std::fmt;
///
/// struct Length(i32);
///
/// impl fmt::LowerHex for Length {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         let val = self.0;
///
///         fmt::LowerHex::fmt(&val, f) // 委托给 i32 的实现
///     }
/// }
///
/// let l = Length(9);
///
/// assert_eq!(format!("l as hex is: {l:x}"), "l as hex is: 9");
///
/// assert_eq!(format!("l as hex is: {l:#010x}"), "l as hex is: 0x00000009");
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
pub trait LowerHex {
    /// 使用给定的格式化程序格式化该值。
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

/// `X` 格式。
///
/// `UpperHex` trait 应该将其输出格式设置为十六进制数字，其中 `A` 至 `F` 为大写形式。
///
/// 对于原始有符号整数 (`i8` 至 `i128` 和 `isize`)，负值的格式设置为二进制补码表示形式。
///
///
/// 备用标志 `#` 在输出前面添加 `0x`。
///
/// 有关格式化程序的更多信息，请参见 [模块级文档][module]。
///
/// [module]: ../../std/fmt/index.html
///
/// # Examples
///
/// `i32` 的基本用法：
///
/// ```
/// let x = 42; // 42 是十六进制的 '2A'
///
/// assert_eq!(format!("{x:X}"), "2A");
/// assert_eq!(format!("{x:#X}"), "0x2A");
///
/// assert_eq!(format!("{:X}", -16), "FFFFFFF0");
/// ```
///
/// 在类型上实现 `UpperHex`：
///
/// ```
/// use std::fmt;
///
/// struct Length(i32);
///
/// impl fmt::UpperHex for Length {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         let val = self.0;
///
///         fmt::UpperHex::fmt(&val, f) // 委托给 i32 的实现
///     }
/// }
///
/// let l = Length(i32::MAX);
///
/// assert_eq!(format!("l as hex is: {l:X}"), "l as hex is: 7FFFFFFF");
///
/// assert_eq!(format!("l as hex is: {l:#010X}"), "l as hex is: 0x7FFFFFFF");
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
pub trait UpperHex {
    /// 使用给定的格式化程序格式化该值。
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

/// `p` 格式。
///
/// `Pointer` trait 应该将其输出格式化为存储位置。
/// 通常以十六进制表示。
///
/// 有关格式化程序的更多信息，请参见 [模块级文档][module]。
///
/// [module]: ../../std/fmt/index.html
///
/// # Examples
///
/// `&i32` 的基本用法：
///
/// ```
/// let x = &42;
///
/// let address = format!("{x:p}"); // 这会产生类似 '0x7f06092ac6d0' 的东西
/// ```
///
/// 在类型上实现 `Pointer`：
///
/// ```
/// use std::fmt;
///
/// struct Length(i32);
///
/// impl fmt::Pointer for Length {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         // 使用 `as` 转换为 `*const T`，该 `*const T` 实现了 Pointer，我们可以使用它
///
///         let ptr = self as *const Self;
///         fmt::Pointer::fmt(&ptr, f)
///     }
/// }
///
/// let l = Length(42);
///
/// println!("l is in memory here: {l:p}");
///
/// let l_ptr = format!("{l:018p}");
/// assert_eq!(l_ptr.len(), 18);
/// assert_eq!(&l_ptr[..2], "0x");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_diagnostic_item = "Pointer"]
pub trait Pointer {
    /// 使用给定的格式化程序格式化该值。
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

/// `e` 格式。
///
/// `LowerExp` trait 应该使用小写的 `e` 以科学计数法格式化其输出。
///
/// 有关格式化程序的更多信息，请参见 [模块级文档][module]。
///
/// [module]: ../../std/fmt/index.html
///
/// # Examples
///
/// `f64` 的基本用法：
///
/// ```
/// let x = 42.0; // 42.0 是 '4.2e1' 的科学计数形式
///
/// assert_eq!(format!("{x:e}"), "4.2e1");
/// ```
///
/// 在类型上实现 `LowerExp`：
///
/// ```
/// use std::fmt;
///
/// struct Length(i32);
///
/// impl fmt::LowerExp for Length {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         let val = f64::from(self.0);
///         fmt::LowerExp::fmt(&val, f) // 委托 f64 的实现
///     }
/// }
///
/// let l = Length(100);
///
/// assert_eq!(
///     format!("l in scientific notation is: {l:e}"),
///     "l in scientific notation is: 1e2"
/// );
///
/// assert_eq!(
///     format!("l in scientific notation is: {l:05e}"),
///     "l in scientific notation is: 001e2"
/// );
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub trait LowerExp {
    /// 使用给定的格式化程序格式化该值。
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

/// `E` 格式。
///
/// `UpperExp` trait 应该使用大写的 `E` 以科学计数法格式化其输出。
///
/// 有关格式化程序的更多信息，请参见 [模块级文档][module]。
///
/// [module]: ../../std/fmt/index.html
///
/// # Examples
///
/// `f64` 的基本用法：
///
/// ```
/// let x = 42.0; // 42.0 是 '4.2E1' 的科学计数形式
///
/// assert_eq!(format!("{x:E}"), "4.2E1");
/// ```
///
/// 在类型上实现 `UpperExp`：
///
/// ```
/// use std::fmt;
///
/// struct Length(i32);
///
/// impl fmt::UpperExp for Length {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         let val = f64::from(self.0);
///         fmt::UpperExp::fmt(&val, f) // 委托 f64 的实现
///     }
/// }
///
/// let l = Length(100);
///
/// assert_eq!(
///     format!("l in scientific notation is: {l:E}"),
///     "l in scientific notation is: 1E2"
/// );
///
/// assert_eq!(
///     format!("l in scientific notation is: {l:05E}"),
///     "l in scientific notation is: 001E2"
/// );
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub trait UpperExp {
    /// 使用给定的格式化程序格式化该值。
    #[stable(feature = "rust1", since = "1.0.0")]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

/// `write` 函数接受一个输出流，以及一个可以与 `format_args!` 宏预编译的 `Arguments` 结构体。
///
///
/// 参数将根据指定的格式字符串格式化为提供的输出流。
///
/// # Examples
///
/// 基本用法：
///
/// ```
/// use std::fmt;
///
/// let mut output = String::new();
/// fmt::write(&mut output, format_args!("Hello {}!", "world"))
///     .expect("Error occurred while trying to write in String");
/// assert_eq!(output, "Hello world!");
/// ```
///
/// 请注意，使用 [`write!`] 可能更可取。Example:
///
/// ```
/// use std::fmt::Write;
///
/// let mut output = String::new();
/// write!(&mut output, "Hello {}!", "world")
///     .expect("Error occurred while trying to write in String");
/// assert_eq!(output, "Hello world!");
/// ```
///
/// [`write!`]: crate::write!
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn write(output: &mut dyn Write, args: Arguments<'_>) -> Result {
    let mut formatter = Formatter::new(output);
    let mut idx = 0;

    match args.fmt {
        None => {
            // 我们可以对所有参数使用默认格式设置参数。
            for (i, arg) in args.args.iter().enumerate() {
                // SAFETY: args.args 和 args.pieces 来自同一个参数，保证索引总是在限定范围内。
                //
                let piece = unsafe { args.pieces.get_unchecked(i) };
                if !piece.is_empty() {
                    formatter.buf.write_str(*piece)?;
                }
                arg.fmt(&mut formatter)?;
                idx += 1;
            }
        }
        Some(fmt) => {
            // 每个规范都有一个对应的参数，该参数后有一个字符串。
            //
            for (i, arg) in fmt.iter().enumerate() {
                // SAFETY: fmt 和 args.pieces 来自同一个 参数，保证索引总是在限定范围内。
                //
                let piece = unsafe { args.pieces.get_unchecked(i) };
                if !piece.is_empty() {
                    formatter.buf.write_str(*piece)?;
                }
                // SAFETY: arg 和 args.args 来自相同的参数，从而确保索引始终在范围之内。
                //
                unsafe { run(&mut formatter, arg, args.args) }?;
                idx += 1;
            }
        }
    }

    // 只能剩下一个尾随的字符串切片。
    if let Some(piece) = args.pieces.get(idx) {
        formatter.buf.write_str(*piece)?;
    }

    Ok(())
}

unsafe fn run(fmt: &mut Formatter<'_>, arg: &rt::Placeholder, args: &[rt::Argument<'_>]) -> Result {
    fmt.fill = arg.fill;
    fmt.align = arg.align;
    fmt.flags = arg.flags;
    // SAFETY: arg 和 args 来自相同的参数，从而确保索引始终在范围之内。
    //
    unsafe {
        fmt.width = getcount(args, &arg.width);
        fmt.precision = getcount(args, &arg.precision);
    }

    // 提取正确的参数
    debug_assert!(arg.position < args.len());
    // SAFETY: arg 和 args 来自相同的参数，从而确保其索引始终在范围之内。
    //
    let value = unsafe { args.get_unchecked(arg.position) };

    // 然后实际做一些打印
    value.fmt(fmt)
}

unsafe fn getcount(args: &[rt::Argument<'_>], cnt: &rt::Count) -> Option<usize> {
    match *cnt {
        rt::Count::Is(n) => Some(n),
        rt::Count::Implied => None,
        rt::Count::Param(i) => {
            debug_assert!(i < args.len());
            // SAFETY: cnt 和 args 来自相同的参数，这确保此索引始终在范围之内。
            //
            unsafe { args.get_unchecked(i).as_usize() }
        }
    }
}

/// 结束后填充。由 `Formatter::padding` 返回。
#[must_use = "don't forget to write the post padding"]
pub(crate) struct PostPadding {
    fill: char,
    padding: usize,
}

impl PostPadding {
    fn new(fill: char, padding: usize) -> PostPadding {
        PostPadding { fill, padding }
    }

    /// 写这篇文章补充。
    pub(crate) fn write(self, f: &mut Formatter<'_>) -> Result {
        for _ in 0..self.padding {
            f.buf.write_char(self.fill)?;
        }
        Ok(())
    }
}

impl<'a> Formatter<'a> {
    fn wrap_buf<'b, 'c, F>(&'b mut self, wrap: F) -> Formatter<'c>
    where
        'b: 'c,
        F: FnOnce(&'b mut (dyn Write + 'b)) -> &'c mut (dyn Write + 'c),
    {
        Formatter {
            // 我们要改变这个
            buf: wrap(self.buf),

            // 并保留这些
            flags: self.flags,
            fill: self.fill,
            align: self.align,
            width: self.width,
            precision: self.precision,
        }
    }

    // 用于填充和处理格式化参数的辅助方法，所有格式化 traits 都可以使用。
    //

    /// 对已经发出到 str 中的整数执行正确的填充。
    /// str *不应* 包含整数的符号，该符号将通过此方法添加。
    ///
    /// # Arguments
    ///
    /// * is_nonnegative - 原始整数是正数还是零。
    /// * prefix - 如果提供了 '#' 字符 (Alternate)，则这是放在数字前面的前缀。
    ///
    /// * buf - 数字已格式化为的字节数组
    ///
    /// 此函数将正确说明提供的标志以及最小宽度。
    /// 它不会考虑精度。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo { nb: i32 }
    ///
    /// impl Foo {
    ///     fn new(nb: i32) -> Foo {
    ///         Foo {
    ///             nb,
    ///         }
    ///     }
    /// }
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         // 我们需要从数字输出中删除 "-"。
    ///         let tmp = self.nb.abs().to_string();
    ///
    ///         formatter.pad_integral(self.nb >= 0, "Foo ", &tmp)
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{}", Foo::new(2)), "2");
    /// assert_eq!(format!("{}", Foo::new(-1)), "-1");
    /// assert_eq!(format!("{}", Foo::new(0)), "0");
    /// assert_eq!(format!("{:#}", Foo::new(-1)), "-Foo 1");
    /// assert_eq!(format!("{:0>#8}", Foo::new(-1)), "00-Foo 1");
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn pad_integral(&mut self, is_nonnegative: bool, prefix: &str, buf: &str) -> Result {
        let mut width = buf.len();

        let mut sign = None;
        if !is_nonnegative {
            sign = Some('-');
            width += 1;
        } else if self.sign_plus() {
            sign = Some('+');
            width += 1;
        }

        let prefix = if self.alternate() {
            width += prefix.chars().count();
            Some(prefix)
        } else {
            None
        };

        // 写入符号 (如果存在)，然后写入前缀 (如果已请求)
        #[inline(never)]
        fn write_prefix(f: &mut Formatter<'_>, sign: Option<char>, prefix: Option<&str>) -> Result {
            if let Some(c) = sign {
                f.buf.write_char(c)?;
            }
            if let Some(prefix) = prefix { f.buf.write_str(prefix) } else { Ok(()) }
        }

        // 此时，`width` 字段更多是 `min-width` 参数。
        match self.width {
            // 如果没有最小长度要求，那么我们可以写字节。
            //
            None => {
                write_prefix(self, sign, prefix)?;
                self.buf.write_str(buf)
            }
            // 检查是否超过最小宽度，如果是，那么我们也可以只写字节。
            //
            Some(min) if width >= min => {
                write_prefix(self, sign, prefix)?;
                self.buf.write_str(buf)
            }
            // 如果填充字符为零，则符号和前缀位于填充之前
            //
            Some(min) if self.sign_aware_zero_pad() => {
                let old_fill = crate::mem::replace(&mut self.fill, '0');
                let old_align = crate::mem::replace(&mut self.align, rt::Alignment::Right);
                write_prefix(self, sign, prefix)?;
                let post_padding = self.padding(min - width, Alignment::Right)?;
                self.buf.write_str(buf)?;
                post_padding.write(self)?;
                self.fill = old_fill;
                self.align = old_align;
                Ok(())
            }
            // 否则，符号和前缀在填充之后
            Some(min) => {
                let post_padding = self.padding(min - width, Alignment::Right)?;
                write_prefix(self, sign, prefix)?;
                self.buf.write_str(buf)?;
                post_padding.write(self)
            }
        }
    }

    /// 应用指定的相关格式设置标志后，此函数将获取一个字符串切片并将其发送到内部缓冲区。
    /// 泛型字符串可识别的标志为：
    ///
    /// * width - 发射的最小宽度
    /// * fill/align - 如果需要填充提供的字符串，要发出什么以及在哪里发出
    /// * precision - 发出的最大长度，如果字符串长于该长度，则字符串将被截断
    ///
    /// 值得注意的是，此函数将忽略 `flag` 参数。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo;
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         formatter.pad("Foo")
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{Foo:<4}"), "Foo ");
    /// assert_eq!(format!("{Foo:0>4}"), "0Foo");
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn pad(&mut self, s: &str) -> Result {
        // 确保前面有一条快速路
        if self.width.is_none() && self.precision.is_none() {
            return self.buf.write_str(s);
        }
        // 对于要格式化的字符串，`precision` 字段可以解释为 `max-width`。
        //
        let s = if let Some(max) = self.precision {
            // 如果我们的字符串比精度更长，那么我们必须将其截断。
            // 但是，其他标志 (例如 `fill`，`width` 和 `align`) 必须照常运行。
            //
            if let Some((i, _)) = s.char_indices().nth(max) {
                // 此处的 LLVM 不能证明 `..i` 不会 panic `&s[..i]`，但是我们知道它不能 panic。
                // 使用 `get` + `unwrap_or` 避免使用 `unsafe`，否则请不要在此处发出任何与 panic 相关的代码。
                //
                //
                s.get(..i).unwrap_or(s)
            } else {
                &s
            }
        } else {
            &s
        };
        // 此时，`width` 字段更多是 `min-width` 参数。
        match self.width {
            // 如果我们在最大长度以下，并且没有最小长度要求，那么我们就可以发出字符串
            //
            None => self.buf.write_str(s),
            Some(width) => {
                let chars_count = s.chars().count();
                // 如果我们在最大宽度之下，请检查我们是否在最小宽度之上，如果是，那么就和发出字符串一样容易。
                //
                if chars_count >= width {
                    self.buf.write_str(s)
                }
                // 如果我们同时处于最大和最小宽度之下，则使用指定的字符串 + 某些对齐方式来填充最小宽度。
                //
                else {
                    let align = Alignment::Left;
                    let post_padding = self.padding(width - chars_count, align)?;
                    self.buf.write_str(s)?;
                    post_padding.write(self)
                }
            }
        }
    }

    /// 编写前填充并返回未写的后填充。
    /// 调用者有责任确保在填充内容之后编写填充后的内容。
    ///
    pub(crate) fn padding(
        &mut self,
        padding: usize,
        default: Alignment,
    ) -> result::Result<PostPadding, Error> {
        let align = match self.align {
            rt::Alignment::Unknown => default,
            rt::Alignment::Left => Alignment::Left,
            rt::Alignment::Right => Alignment::Right,
            rt::Alignment::Center => Alignment::Center,
        };

        let (pre_pad, post_pad) = match align {
            Alignment::Left => (0, padding),
            Alignment::Right => (padding, 0),
            Alignment::Center => (padding / 2, (padding + 1) / 2),
        };

        for _ in 0..pre_pad {
            self.buf.write_char(self.fill)?;
        }

        Ok(PostPadding::new(self.fill, post_pad))
    }

    /// 取出格式化的部分并应用填充。
    /// 假定调用者已经以所需的精度渲染了零件，因此可以忽略 `self.precision`。
    ///
    ///
    /// # Safety
    ///
    /// `formatted` 中的任何 `numfmt::Part::Copy` 部分都必须包含有效的 UTF-8。
    unsafe fn pad_formatted_parts(&mut self, formatted: &numfmt::Formatted<'_>) -> Result {
        if let Some(mut width) = self.width {
            // 对于可识别符号的零填充，我们首先渲染符号，然后从一开始就表现为没有符号。
            //
            let mut formatted = formatted.clone();
            let old_fill = self.fill;
            let old_align = self.align;
            if self.sign_aware_zero_pad() {
                // 符号总是最先
                let sign = formatted.sign;
                self.buf.write_str(sign)?;

                // 从格式化部分中删除符号
                formatted.sign = "";
                width = width.saturating_sub(sign.len());
                self.fill = '0';
                self.align = rt::Alignment::Right;
            }

            // 其余部分则经过普通的填充过程。
            let len = formatted.len();
            let ret = if width <= len {
                // 没有填充
                // SAFETY: 按前提条件。
                unsafe { self.write_formatted_parts(&formatted) }
            } else {
                let post_padding = self.padding(width - len, Alignment::Right)?;
                // SAFETY: 按前提条件。
                unsafe {
                    self.write_formatted_parts(&formatted)?;
                }
                post_padding.write(self)
            };
            self.fill = old_fill;
            self.align = old_align;
            ret
        } else {
            // 这是常见的情况，我们采取捷径
            // SAFETY: 按前提条件。
            unsafe { self.write_formatted_parts(formatted) }
        }
    }

    /// # Safety
    ///
    /// `formatted` 中的任何 `numfmt::Part::Copy` 部分都必须包含有效的 UTF-8。
    unsafe fn write_formatted_parts(&mut self, formatted: &numfmt::Formatted<'_>) -> Result {
        unsafe fn write_bytes(buf: &mut dyn Write, s: &[u8]) -> Result {
            // SAFETY: 这用于 `numfmt::Part::Num` 和 `numfmt::Part::Copy`。
            // 用于 `numfmt::Part::Num` 是安全的，因为每个字符 `c` 都在 `b'0'` 和 `b'9'` 之间，这意味着 `s` 是有效的 UTF-8。
            // 由于这个函数的前提条件，因此可以安全地用于 `numfmt::Part::Copy`。
            //
            buf.write_str(unsafe { str::from_utf8_unchecked(s) })
        }

        if !formatted.sign.is_empty() {
            self.buf.write_str(formatted.sign)?;
        }
        for part in formatted.parts {
            match *part {
                numfmt::Part::Zero(mut nzeroes) => {
                    const ZEROES: &str = // 64 个零
                        "0000000000000000000000000000000000000000000000000000000000000000";
                    while nzeroes > ZEROES.len() {
                        self.buf.write_str(ZEROES)?;
                        nzeroes -= ZEROES.len();
                    }
                    if nzeroes > 0 {
                        self.buf.write_str(&ZEROES[..nzeroes])?;
                    }
                }
                numfmt::Part::Num(mut v) => {
                    let mut s = [0; 5];
                    let len = part.len();
                    for c in s[..len].iter_mut().rev() {
                        *c = b'0' + (v % 10) as u8;
                        v /= 10;
                    }
                    // SAFETY: 按前提条件。
                    unsafe {
                        write_bytes(self.buf, &s[..len])?;
                    }
                }
                // SAFETY: 按前提条件。
                numfmt::Part::Copy(buf) => unsafe {
                    write_bytes(self.buf, buf)?;
                },
            }
        }
        Ok(())
    }

    /// 将一些数据写入此格式化程序中包含的底层缓冲区。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo;
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         formatter.write_str("Foo")
    ///         // 这相当于：
    ///         // write!(formatter, "Foo")
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{Foo}"), "Foo");
    /// assert_eq!(format!("{Foo:0>8}"), "Foo");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn write_str(&mut self, data: &str) -> Result {
        self.buf.write_str(data)
    }

    /// 将一些格式化的信息写入此实例。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo(i32);
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         formatter.write_fmt(format_args!("Foo {}", self.0))
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{}", Foo(-1)), "Foo -1");
    /// assert_eq!(format!("{:0>8}", Foo(2)), "Foo 2");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result {
        write(self.buf, fmt)
    }

    /// 格式化标志
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[deprecated(
        since = "1.24.0",
        note = "use the `sign_plus`, `sign_minus`, `alternate`, \
                or `sign_aware_zero_pad` methods instead"
    )]
    pub fn flags(&self) -> u32 {
        self.flags
    }

    /// 对齐时用作 'fill' 的字符。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo;
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         let c = formatter.fill();
    ///         if let Some(width) = formatter.width() {
    ///             for _ in 0..width {
    ///                 write!(formatter, "{c}")?;
    ///             }
    ///             Ok(())
    ///         } else {
    ///             write!(formatter, "{c}")
    ///         }
    ///     }
    /// }
    ///
    /// // 我们使用 ">" 在右边设置对齐方式。
    /// assert_eq!(format!("{Foo:G>3}"), "GGG");
    /// assert_eq!(format!("{Foo:t>6}"), "tttttt");
    /// ```
    #[must_use]
    #[stable(feature = "fmt_flags", since = "1.5.0")]
    pub fn fill(&self) -> char {
        self.fill
    }

    /// 指示请求对齐方式的标志。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt::{self, Alignment};
    ///
    /// struct Foo;
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         let s = if let Some(s) = formatter.align() {
    ///             match s {
    ///                 Alignment::Left    => "left",
    ///                 Alignment::Right   => "right",
    ///                 Alignment::Center  => "center",
    ///             }
    ///         } else {
    ///             "into the void"
    ///         };
    ///         write!(formatter, "{s}")
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{Foo:<}"), "left");
    /// assert_eq!(format!("{Foo:>}"), "right");
    /// assert_eq!(format!("{Foo:^}"), "center");
    /// assert_eq!(format!("{Foo}"), "into the void");
    /// ```
    #[must_use]
    #[stable(feature = "fmt_flags_align", since = "1.28.0")]
    pub fn align(&self) -> Option<Alignment> {
        match self.align {
            rt::Alignment::Left => Some(Alignment::Left),
            rt::Alignment::Right => Some(Alignment::Right),
            rt::Alignment::Center => Some(Alignment::Center),
            rt::Alignment::Unknown => None,
        }
    }

    /// (可选) 指定输出应为的整数宽度。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo(i32);
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         if let Some(width) = formatter.width() {
    ///             // 如果我们收到一个宽度，我们就用它
    ///             write!(formatter, "{:width$}", format!("Foo({})", self.0), width = width)
    ///         } else {
    ///             // 否则我们没什么特别的
    ///             write!(formatter, "Foo({})", self.0)
    ///         }
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{:10}", Foo(23)), "Foo(23)   ");
    /// assert_eq!(format!("{}", Foo(23)), "Foo(23)");
    /// ```
    #[must_use]
    #[stable(feature = "fmt_flags", since = "1.5.0")]
    pub fn width(&self) -> Option<usize> {
        self.width
    }

    /// 可选地为数字类型指定精度。
    /// 或者，为字符串类型的最大宽度。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo(f32);
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         if let Some(precision) = formatter.precision() {
    ///             // 如果我们收到了精度，我们就会使用它。
    ///             write!(formatter, "Foo({1:.*})", precision, self.0)
    ///         } else {
    ///             // 否则我们默认为 2.
    ///             write!(formatter, "Foo({:.2})", self.0)
    ///         }
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{:.4}", Foo(23.2)), "Foo(23.2000)");
    /// assert_eq!(format!("{}", Foo(23.2)), "Foo(23.20)");
    /// ```
    #[must_use]
    #[stable(feature = "fmt_flags", since = "1.5.0")]
    pub fn precision(&self) -> Option<usize> {
        self.precision
    }

    /// 确定是否指定了 `+` 标志。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo(i32);
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         if formatter.sign_plus() {
    ///             write!(formatter,
    ///                    "Foo({}{})",
    ///                    if self.0 < 0 { '-' } else { '+' },
    ///                    self.0.abs())
    ///         } else {
    ///             write!(formatter, "Foo({})", self.0)
    ///         }
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{:+}", Foo(23)), "Foo(+23)");
    /// assert_eq!(format!("{:+}", Foo(-23)), "Foo(-23)");
    /// assert_eq!(format!("{}", Foo(23)), "Foo(23)");
    /// ```
    #[must_use]
    #[stable(feature = "fmt_flags", since = "1.5.0")]
    pub fn sign_plus(&self) -> bool {
        self.flags & (1 << rt::Flag::SignPlus as u32) != 0
    }

    /// 确定是否指定了 `-` 标志。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo(i32);
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         if formatter.sign_minus() {
    ///             // 您想要一个减号？ 有一个！
    ///             write!(formatter, "-Foo({})", self.0)
    ///         } else {
    ///             write!(formatter, "Foo({})", self.0)
    ///         }
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{:-}", Foo(23)), "-Foo(23)");
    /// assert_eq!(format!("{}", Foo(23)), "Foo(23)");
    /// ```
    #[must_use]
    #[stable(feature = "fmt_flags", since = "1.5.0")]
    pub fn sign_minus(&self) -> bool {
        self.flags & (1 << rt::Flag::SignMinus as u32) != 0
    }

    /// 确定是否指定了 `#` 标志。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo(i32);
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         if formatter.alternate() {
    ///             write!(formatter, "Foo({})", self.0)
    ///         } else {
    ///             write!(formatter, "{}", self.0)
    ///         }
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{:#}", Foo(23)), "Foo(23)");
    /// assert_eq!(format!("{}", Foo(23)), "23");
    /// ```
    #[must_use]
    #[stable(feature = "fmt_flags", since = "1.5.0")]
    pub fn alternate(&self) -> bool {
        self.flags & (1 << rt::Flag::Alternate as u32) != 0
    }

    /// 确定是否指定了 `0` 标志。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fmt;
    ///
    /// struct Foo(i32);
    ///
    /// impl fmt::Display for Foo {
    ///     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         assert!(formatter.sign_aware_zero_pad());
    ///         assert_eq!(formatter.width(), Some(4));
    ///         // 我们忽略格式化程序的选项。
    ///         write!(formatter, "{}", self.0)
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{:04}", Foo(23)), "23");
    /// ```
    #[must_use]
    #[stable(feature = "fmt_flags", since = "1.5.0")]
    pub fn sign_aware_zero_pad(&self) -> bool {
        self.flags & (1 << rt::Flag::SignAwareZeroPad as u32) != 0
    }

    // FIXME: 确定我们要为这两个标志使用的公共 API。
    // https://github.com/rust-lang/rust/issues/48584
    fn debug_lower_hex(&self) -> bool {
        self.flags & (1 << rt::Flag::DebugLowerHex as u32) != 0
    }

    fn debug_upper_hex(&self) -> bool {
        self.flags & (1 << rt::Flag::DebugUpperHex as u32) != 0
    }

    /// 创建一个 [`DebugStruct`] 构建器，该构建器旨在帮助创建结构体的 [`fmt::Debug`] 实现。
    ///
    ///
    /// [`fmt::Debug`]: self::Debug
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::fmt;
    /// use std::net::Ipv4Addr;
    ///
    /// struct Foo {
    ///     bar: i32,
    ///     baz: String,
    ///     addr: Ipv4Addr,
    /// }
    ///
    /// impl fmt::Debug for Foo {
    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         fmt.debug_struct("Foo")
    ///             .field("bar", &self.bar)
    ///             .field("baz", &self.baz)
    ///             .field("addr", &format_args!("{}", self.addr))
    ///             .finish()
    ///     }
    /// }
    ///
    /// 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> {
        builders::debug_struct_new(self, name)
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_struct_fields_finish` 更通用，但对于 1 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_struct_field1_finish<'b>(
        &'b mut self,
        name: &str,
        name1: &str,
        value1: &dyn Debug,
    ) -> Result {
        let mut builder = builders::debug_struct_new(self, name);
        builder.field(name1, value1);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_struct_fields_finish` 更通用，但这对于 2 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_struct_field2_finish<'b>(
        &'b mut self,
        name: &str,
        name1: &str,
        value1: &dyn Debug,
        name2: &str,
        value2: &dyn Debug,
    ) -> Result {
        let mut builder = builders::debug_struct_new(self, name);
        builder.field(name1, value1);
        builder.field(name2, value2);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_struct_fields_finish` 更通用，但对于 3 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_struct_field3_finish<'b>(
        &'b mut self,
        name: &str,
        name1: &str,
        value1: &dyn Debug,
        name2: &str,
        value2: &dyn Debug,
        name3: &str,
        value3: &dyn Debug,
    ) -> Result {
        let mut builder = builders::debug_struct_new(self, name);
        builder.field(name1, value1);
        builder.field(name2, value2);
        builder.field(name3, value3);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_struct_fields_finish` 更通用，但对于 4 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_struct_field4_finish<'b>(
        &'b mut self,
        name: &str,
        name1: &str,
        value1: &dyn Debug,
        name2: &str,
        value2: &dyn Debug,
        name3: &str,
        value3: &dyn Debug,
        name4: &str,
        value4: &dyn Debug,
    ) -> Result {
        let mut builder = builders::debug_struct_new(self, name);
        builder.field(name1, value1);
        builder.field(name2, value2);
        builder.field(name3, value3);
        builder.field(name4, value4);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_struct_fields_finish` 更通用，但对于 5 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_struct_field5_finish<'b>(
        &'b mut self,
        name: &str,
        name1: &str,
        value1: &dyn Debug,
        name2: &str,
        value2: &dyn Debug,
        name3: &str,
        value3: &dyn Debug,
        name4: &str,
        value4: &dyn Debug,
        name5: &str,
        value5: &dyn Debug,
    ) -> Result {
        let mut builder = builders::debug_struct_new(self, name);
        builder.field(name1, value1);
        builder.field(name2, value2);
        builder.field(name3, value3);
        builder.field(name4, value4);
        builder.field(name5, value5);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// 对于 `debug_struct_field[12345]_finish` 未涵盖的情况。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_struct_fields_finish<'b>(
        &'b mut self,
        name: &str,
        names: &[&str],
        values: &[&dyn Debug],
    ) -> Result {
        assert_eq!(names.len(), values.len());
        let mut builder = builders::debug_struct_new(self, name);
        for (name, value) in iter::zip(names, values) {
            builder.field(name, value);
        }
        builder.finish()
    }

    /// 创建一个 `DebugTuple` 构建器，该构建器旨在协助创建元组结构体的 `fmt::Debug` 实现。
    ///
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::fmt;
    /// use std::marker::PhantomData;
    ///
    /// struct Foo<T>(i32, String, PhantomData<T>);
    ///
    /// 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()
    ///     }
    /// }
    ///
    /// 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> {
        builders::debug_tuple_new(self, name)
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_tuple_fields_finish` 更通用，但对于 1 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_tuple_field1_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug) -> Result {
        let mut builder = builders::debug_tuple_new(self, name);
        builder.field(value1);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_tuple_fields_finish` 更通用，但这对于 2 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_tuple_field2_finish<'b>(
        &'b mut self,
        name: &str,
        value1: &dyn Debug,
        value2: &dyn Debug,
    ) -> Result {
        let mut builder = builders::debug_tuple_new(self, name);
        builder.field(value1);
        builder.field(value2);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_tuple_fields_finish` 更通用，但对于 3 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_tuple_field3_finish<'b>(
        &'b mut self,
        name: &str,
        value1: &dyn Debug,
        value2: &dyn Debug,
        value3: &dyn Debug,
    ) -> Result {
        let mut builder = builders::debug_tuple_new(self, name);
        builder.field(value1);
        builder.field(value2);
        builder.field(value3);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_tuple_fields_finish` 更通用，但对于 4 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_tuple_field4_finish<'b>(
        &'b mut self,
        name: &str,
        value1: &dyn Debug,
        value2: &dyn Debug,
        value3: &dyn Debug,
        value4: &dyn Debug,
    ) -> Result {
        let mut builder = builders::debug_tuple_new(self, name);
        builder.field(value1);
        builder.field(value2);
        builder.field(value3);
        builder.field(value4);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// `debug_tuple_fields_finish` 更通用，但对于 5 个字段来说更快。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_tuple_field5_finish<'b>(
        &'b mut self,
        name: &str,
        value1: &dyn Debug,
        value2: &dyn Debug,
        value3: &dyn Debug,
        value4: &dyn Debug,
        value5: &dyn Debug,
    ) -> Result {
        let mut builder = builders::debug_tuple_new(self, name);
        builder.field(value1);
        builder.field(value2);
        builder.field(value3);
        builder.field(value4);
        builder.field(value5);
        builder.finish()
    }

    /// 用于缩小 `derive(Debug)` 代码，以实现更快的编译和更小的二进制文件。
    /// 对于 `debug_tuple_field[12345]_finish` 未涵盖的情况。
    #[doc(hidden)]
    #[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
    pub fn debug_tuple_fields_finish<'b>(
        &'b mut self,
        name: &str,
        values: &[&dyn Debug],
    ) -> Result {
        let mut builder = builders::debug_tuple_new(self, name);
        for value in values {
            builder.field(value);
        }
        builder.finish()
    }

    /// 创建一个 `DebugList` 构建器，该构建器旨在帮助为类似列表的结构创建 `fmt::Debug` 实现。
    ///
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::fmt;
    ///
    /// struct Foo(Vec<i32>);
    ///
    /// impl fmt::Debug for Foo {
    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         fmt.debug_list().entries(self.0.iter()).finish()
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{:?}", Foo(vec![10, 11])), "[10, 11]");
    /// ```
    #[stable(feature = "debug_builders", since = "1.2.0")]
    pub fn debug_list<'b>(&'b mut self) -> DebugList<'b, 'a> {
        builders::debug_list_new(self)
    }

    /// 创建一个 `DebugSet` 构建器，该构建器旨在帮助为类似集合的结构创建 `fmt::Debug` 实现。
    ///
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::fmt;
    ///
    /// struct Foo(Vec<i32>);
    ///
    /// impl fmt::Debug for Foo {
    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         fmt.debug_set().entries(self.0.iter()).finish()
    ///     }
    /// }
    ///
    /// assert_eq!(format!("{:?}", Foo(vec![10, 11])), "{10, 11}");
    /// ```
    ///
    /// [`format_args!`]: crate::format_args
    ///
    /// 在这个更复杂的示例中，我们使用 [`format_args!`] 和 `.debug_set()` 来构建匹配分支的列表：
    ///
    /// ```rust
    /// use std::fmt;
    ///
    /// struct Arm<'a, L, R>(&'a (L, R));
    /// struct Table<'a, K, V>(&'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)
    }

    /// 创建一个 `DebugMap` 构建器，该构建器旨在帮助为类似 map 的结构创建 `fmt::Debug` 实现。
    ///
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::fmt;
    ///
    /// struct Foo(Vec<(String, i32)>);
    ///
    /// impl fmt::Debug for Foo {
    ///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
    ///         fmt.debug_map().entries(self.0.iter().map(|&(ref k, ref v)| (k, v))).finish()
    ///     }
    /// }
    ///
    /// assert_eq!(
    ///     format!("{:?}",  Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    ///     r#"{"A": 10, "B": 11}"#
    ///  );
    /// ```
    #[stable(feature = "debug_builders", since = "1.2.0")]
    pub fn debug_map<'b>(&'b mut self) -> DebugMap<'b, 'a> {
        builders::debug_map_new(self)
    }
}

#[stable(since = "1.2.0", feature = "formatter_write")]
impl Write for Formatter<'_> {
    fn write_str(&mut self, s: &str) -> Result {
        self.buf.write_str(s)
    }

    fn write_char(&mut self, c: char) -> Result {
        self.buf.write_char(c)
    }

    fn write_fmt(&mut self, args: Arguments<'_>) -> Result {
        write(self.buf, args)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Display for Error {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Display::fmt("an error occurred when formatting an argument", f)
    }
}

// 核心格式 traits 的实现

macro_rules! fmt_refs {
    ($($tr:ident),*) => {
        $(
        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized + $tr> $tr for &T {
            fn fmt(&self, f: &mut Formatter<'_>) -> Result { $tr::fmt(&**self, f) }
        }
        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized + $tr> $tr for &mut T {
            fn fmt(&self, f: &mut Formatter<'_>) -> Result { $tr::fmt(&**self, f) }
        }
        )*
    }
}

fmt_refs! { Debug, Display, Octal, Binary, LowerHex, UpperHex, LowerExp, UpperExp }

#[unstable(feature = "never_type", issue = "35121")]
impl Debug for ! {
    #[inline]
    fn fmt(&self, _: &mut Formatter<'_>) -> Result {
        *self
    }
}

#[unstable(feature = "never_type", issue = "35121")]
impl Display for ! {
    #[inline]
    fn fmt(&self, _: &mut Formatter<'_>) -> Result {
        *self
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Debug for bool {
    #[inline]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Display::fmt(self, f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Display for bool {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Display::fmt(if *self { "true" } else { "false" }, f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Debug for str {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.write_char('"')?;
        let mut from = 0;
        for (i, c) in self.char_indices() {
            let esc = c.escape_debug_ext(EscapeDebugExtArgs {
                escape_grapheme_extended: true,
                escape_single_quote: false,
                escape_double_quote: true,
            });
            // 如果 char 需要转义，请清除到目前为止的积压并编写，否则跳过
            if esc.len() != 1 {
                f.write_str(&self[from..i])?;
                for c in esc {
                    f.write_char(c)?;
                }
                from = i + c.len_utf8();
            }
        }
        f.write_str(&self[from..])?;
        f.write_char('"')
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Display for str {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.pad(self)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Debug for char {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.write_char('\'')?;
        for c in self.escape_debug_ext(EscapeDebugExtArgs {
            escape_grapheme_extended: true,
            escape_single_quote: true,
            escape_double_quote: false,
        }) {
            f.write_char(c)?
        }
        f.write_char('\'')
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Display for char {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        if f.width.is_none() && f.precision.is_none() {
            f.write_char(*self)
        } else {
            f.pad(self.encode_utf8(&mut [0; 4]))
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Pointer for *const T {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        // 这里需要 Cast，因为 `.expose_addr()` 需要 `T: Sized`。
        pointer_fmt_inner((*self as *const ()).expose_addr(), f)
    }
}

/// 由于所有指针类型的格式都是相同的，因此对实际格式使用非单态实现以减少所需的 codegen 工作量。
///
///
/// 这使用 `ptr_addr: usize` 而不是 `ptr: *const ()` 能够在不使用 [problematic] "Oxford Casts" 的情况下将其用于 `fn(...) -> ...`。
///
/// [problematic]: https://github.com/rust-lang/rust/issues/95489
///
pub(crate) fn pointer_fmt_inner(ptr_addr: usize, f: &mut Formatter<'_>) -> Result {
    let old_width = f.width;
    let old_flags = f.flags;

    // LowerHex 已将替代标志视为特殊标志，它表示是否以 0x 作为前缀。
    // 我们使用它来计算是否为零扩展，然后无条件地将其设置为获取前缀。
    //
    //
    if f.alternate() {
        f.flags |= 1 << (rt::Flag::SignAwareZeroPad as u32);

        if f.width.is_none() {
            f.width = Some((usize::BITS / 4) as usize + 2);
        }
    }
    f.flags |= 1 << (rt::Flag::Alternate as u32);

    let ret = LowerHex::fmt(&ptr_addr, f);

    f.width = old_width;
    f.flags = old_flags;

    ret
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Pointer for *mut T {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Pointer::fmt(&(*self as *const T), f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Pointer for &T {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Pointer::fmt(&(*self as *const T), f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Pointer for &mut T {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Pointer::fmt(&(&**self as *const T), f)
    }
}

// Display/Debug 在各种核心类型上的实现

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Debug for *const T {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Pointer::fmt(self, f)
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Debug for *mut T {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Pointer::fmt(self, f)
    }
}

macro_rules! peel {
    ($name:ident, $($other:ident,)*) => (tuple! { $($other,)* })
}

macro_rules! tuple {
    () => ();
    ( $($name:ident,)+ ) => (
        maybe_tuple_doc! {
            $($name)+ @
            #[stable(feature = "rust1", since = "1.0.0")]
            impl<$($name:Debug),+> Debug for ($($name,)+) where last_type!($($name,)+): ?Sized {
                #[allow(non_snake_case, unused_assignments)]
                fn fmt(&self, f: &mut Formatter<'_>) -> Result {
                    let mut builder = f.debug_tuple("");
                    let ($(ref $name,)+) = *self;
                    $(
                        builder.field(&$name);
                    )+

                    builder.finish()
                }
            }
        }
        peel! { $($name,)+ }
    )
}

macro_rules! maybe_tuple_doc {
    ($a:ident @ #[$meta:meta] $item:item) => {
        #[doc(fake_variadic)]
        #[doc = "This trait is implemented for tuples up to twelve items long."]
        #[$meta]
        $item
    };
    ($a:ident $($rest_a:ident)+ @ #[$meta:meta] $item:item) => {
        #[doc(hidden)]
        #[$meta]
        $item
    };
}

macro_rules! last_type {
    ($a:ident,) => { $a };
    ($a:ident, $($rest_a:ident,)+) => { last_type!($($rest_a,)+) };
}

tuple! { E, D, C, B, A, Z, Y, X, W, V, U, T, }

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Debug> Debug for [T] {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.debug_list().entries(self.iter()).finish()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Debug for () {
    #[inline]
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.pad("()")
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Debug for PhantomData<T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        write!(f, "PhantomData<{}>", crate::any::type_name::<T>())
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Copy + Debug> Debug for Cell<T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.debug_struct("Cell").field("value", &self.get()).finish()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + Debug> Debug for RefCell<T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        match self.try_borrow() {
            Ok(borrow) => f.debug_struct("RefCell").field("value", &borrow).finish(),
            Err(_) => {
                // RefCell 是可变地借用的，因此我们在这里无法查看其值。
                // 改为显示一个占位符。
                struct BorrowedPlaceholder;

                impl Debug for BorrowedPlaceholder {
                    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
                        f.write_str("<borrowed>")
                    }
                }

                f.debug_struct("RefCell").field("value", &BorrowedPlaceholder).finish()
            }
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + Debug> Debug for Ref<'_, T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Debug::fmt(&**self, f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + Debug> Debug for RefMut<'_, T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        Debug::fmt(&*(self.deref()), f)
    }
}

#[stable(feature = "core_impl_debug", since = "1.9.0")]
impl<T: ?Sized> Debug for UnsafeCell<T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.debug_struct("UnsafeCell").finish_non_exhaustive()
    }
}

#[unstable(feature = "sync_unsafe_cell", issue = "95439")]
impl<T: ?Sized> Debug for SyncUnsafeCell<T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        f.debug_struct("SyncUnsafeCell").finish_non_exhaustive()
    }
}

// 如果您希望测试在这里，请查看 core/tests/fmt.rs 文件，这比在此处创建所有 rt::Piece 结构要容易得多。
//
// alloc crate 中也有测试，用于那些需要分配的测试。