//! 标准库宏
//!
//! 该模块包含一组从标准库导出的宏。
//! 当链接到标准库时，每个宏都可以使用。
//!
// ignore-tidy-dbg

#[doc = include_str!("../../core/src/macros/panic.md")]
#[macro_export]
#[rustc_builtin_macro(std_panic)]
#[stable(feature = "rust1", since = "1.0.0")]
#[allow_internal_unstable(edition_panic)]
#[cfg_attr(not(test), rustc_diagnostic_item = "std_panic_macro")]
macro_rules! panic {
    // 根据调用者的版本扩展为 `$crate::panic::panic_2015` 或 `$crate::panic::panic_2021`。
    //
    ($($arg:tt)*) => {
        /* compiler built-in */
    };
}

/// 打印到标准输出。
///
/// 等效于 [`println!`] 宏，只是在消息末尾不打印换行符。
///
/// 注意，默认情况下，stdout 通常是行缓冲的，因此可能有必要使用 [`io::stdout().flush()`][flush] 以确保立即发出输出。
///
///
/// `print!` 宏将锁定每个调用的标准输出。如果您在热循环内调用 `print!`，则此行为可能是循环的瓶颈。
/// 为了避免这种情况，用 [`io::stdout().lock()`][lock] 锁定 stdout:
///
/// ```
/// use std::io::{stdout, Write};
///
/// let mut lock = stdout().lock();
/// write!(lock, "hello world").unwrap();
/// ```
///
/// `print!` 仅用于程序的主要输出。请改用 [`eprint!`] 打印错误和进度消息。
///
/// [flush]: crate::io::Write::flush
/// [`println!`]: crate::println
/// [`eprint!`]: crate::eprint
/// [lock]: crate::io::Stdout
///
/// # Panics
///
/// 如果写入 `io::stdout()` 失败，就会出现 panics。
///
/// 写入非阻塞 stdout 可能会导致错误，这将导致此宏 panic。
///
/// # Examples
///
/// ```
/// use std::io::{self, Write};
///
/// print!("this ");
/// print!("will ");
/// print!("be ");
/// print!("on ");
/// print!("the ");
/// print!("same ");
/// print!("line ");
///
/// io::stdout().flush().unwrap();
///
/// print!("this string has a newline, why not choose println! instead?\n");
///
/// io::stdout().flush().unwrap();
/// ```
///
///
///
///
#[macro_export]
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "print_macro")]
#[allow_internal_unstable(print_internals)]
macro_rules! print {
    ($($arg:tt)*) => {{
        $crate::io::_print($crate::format_args!($($arg)*));
    }};
}

/// 使用换行符打印到标准输出。
///
/// 在所有平台上，新行是一个换行符 (也就是 `\n`/`U+000A`)，并不包含回车符 (也就是 `\r`/`U+000D`)。
///
///
/// 此宏使用与 [`format!`] 相同的语法，但改为写入标准输出。
/// 有关详细信息，请参见 [`std::fmt`]。
///
/// `println!` 宏将锁定每个调用的标准输出。
/// 如果您在热循环内调用 `println!`，则此行为可能是循环的瓶颈。
/// 为了避免这种情况，用 [`io::stdout().lock()`][lock] 锁定 stdout:
///
/// ```
/// use std::io::{stdout, Write};
///
/// let mut lock = stdout().lock();
/// writeln!(lock, "hello world").unwrap();
/// ```
///
/// `println!` 仅用于程序的主要输出。请改用 [`eprintln!`] 打印错误和进度消息。
///
/// [`std::fmt`]: crate::fmt
/// [`eprintln!`]: crate::eprintln
/// [lock]: crate::io::Stdout
///
/// # Panics
///
/// 如果写入 [`io::stdout`] 失败，就会出现 panics。
///
/// 写入非阻塞 stdout 可能会导致错误，这将导致此宏 panic。
///
/// [`io::stdout`]: crate::io::stdout
///
/// # Examples
///
/// ```
/// println!(); // 只打印换行符
/// println!("hello there!");
/// println!("format {} arguments", "some");
/// let local_variable = "some";
/// println!("format {local_variable} arguments");
/// ```
///
#[macro_export]
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "println_macro")]
#[allow_internal_unstable(print_internals, format_args_nl)]
macro_rules! println {
    () => {
        $crate::print!("\n")
    };
    ($($arg:tt)*) => {{
        $crate::io::_print($crate::format_args_nl!($($arg)*));
    }};
}

/// 打印到标准错误。
///
/// 等效于 [`print!`] 宏，除了输出转到 [`io::stderr`] 而不是 [`io::stdout`]。
///
/// 有关用法示例，请参见 [`print!`]。
///
/// 仅将 `eprint!` 用于错误和进度消息。
/// 改用 `print!` 作为程序的主要输出。
///
/// [`io::stderr`]: crate::io::stderr
/// [`io::stdout`]: crate::io::stdout
///
/// # Panics
///
/// 如果写入 `io::stderr` 失败，就会出现 panics。
///
/// 写入非阻塞 stdout 可能会导致错误，这将导致此宏 panic。
///
/// # Examples
///
/// ```
/// eprint!("Error: Could not complete task");
/// ```
///
#[macro_export]
#[stable(feature = "eprint", since = "1.19.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "eprint_macro")]
#[allow_internal_unstable(print_internals)]
macro_rules! eprint {
    ($($arg:tt)*) => {{
        $crate::io::_eprint($crate::format_args!($($arg)*));
    }};
}

/// 使用换行符打印到标准错误。
///
/// 等效于 [`println!`] 宏，除了输出转到 [`io::stderr`] 而不是 [`io::stdout`]。
///
/// 有关用法示例，请参见 [`println!`]。
///
/// 仅将 `eprintln!` 用于错误和进度消息。
/// 改用 `println!` 作为程序的主要输出。
///
/// [`io::stderr`]: crate::io::stderr
/// [`io::stdout`]: crate::io::stdout
/// [`println!`]: crate::println
///
/// # Panics
///
/// 如果写入 `io::stderr` 失败，就会出现 panics。
///
/// 写入非阻塞 stdout 可能会导致错误，这将导致此宏 panic。
///
/// # Examples
///
/// ```
/// eprintln!("Error: Could not complete task");
/// ```
///
#[macro_export]
#[stable(feature = "eprint", since = "1.19.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "eprintln_macro")]
#[allow_internal_unstable(print_internals, format_args_nl)]
macro_rules! eprintln {
    () => {
        $crate::eprint!("\n")
    };
    ($($arg:tt)*) => {{
        $crate::io::_eprint($crate::format_args_nl!($($arg)*));
    }};
}

/// 打印并返回给定表达式的值，以进行快速而肮脏的调试。
///
/// 一个例子：
///
/// ```rust
/// let a = 2;
/// let b = dbg!(a * 2) + 1;
/// // ^-- 打印: [src/main.rs:2] a * 2 = 4
/// assert_eq!(b, 5);
/// ```
///
/// 宏通过使用给定表达式的类型的 `Debug` 实现将值与宏调用的源位置以及表达式的源代码一起打印到 [标准错误][stderr] 来工作。
///
///
/// 调用表达式上的宏会移动并获取它的所有权，然后再返回不变的求值表达式。
/// 如果表达式的类型未实现 `Copy`，并且您不想放弃所有权，则可以改用 `dbg!(&expr)` 借用某些表达式 `expr`。
///
/// `dbg!` 宏在发行版中的工作原理完全相同。
/// 当仅在发行版本中发生的调试问题或在发行模式下进行的调试明显更快时，此功能很有用。
///
/// 请注意，宏的目的是作为调试工具，因此您应该避免在版本控制中长时间使用它 (测试和类似的情况除外)。
/// 使用其他工具 (例如 [`log`] crate 的 [`debug!`] 宏) 可以更好地完成生产代码的调试输出。
///
/// # Stability
///
/// 不应依赖此宏打印的确切输出，并且可能会受到 future 的更改。
///
/// # Panics
///
/// 如果写入 `io::stderr` 失败，就会出现 panics。
///
/// # 进一步的例子
///
/// 用一种方法：
///
/// ```rust
/// fn foo(n: usize) {
///     if let Some(_) = dbg!(n.checked_sub(4)) {
///         // ...
///     }
/// }
///
/// foo(3)
/// ```
///
/// 打印到 [stderr]：
///
/// ```text,ignore
/// [src/main.rs:4] n.checked_sub(4) = None
/// ```
///
/// 单纯的析因实现：
///
/// ```rust
/// fn factorial(n: u32) -> u32 {
///     if dbg!(n <= 1) {
///         dbg!(1)
///     } else {
///         dbg!(n * factorial(n - 1))
///     }
/// }
///
/// dbg!(factorial(4));
/// ```
///
/// 打印到 [stderr]：
///
/// ```text,ignore
/// [src/main.rs:3] n <= 1 = false
/// [src/main.rs:3] n <= 1 = false
/// [src/main.rs:3] n <= 1 = false
/// [src/main.rs:3] n <= 1 = true
/// [src/main.rs:4] 1 = 1
/// [src/main.rs:5] n * factorial(n - 1) = 2
/// [src/main.rs:5] n * factorial(n - 1) = 6
/// [src/main.rs:5] n * factorial(n - 1) = 24
/// [src/main.rs:11] factorial(4) = 24
/// ```
///
/// `dbg!(..)` 宏移动输入：
///
/// ```compile_fail
/// /// `usize` 的包装器，重要的是它不可复制。
/// #[derive(Debug)]
/// struct NoCopy(usize);
///
/// let a = NoCopy(42);
/// let _ = dbg!(a); // <-- `a` 被移到了这里。
/// let _ = dbg!(a); // <-- `a` 被再次移动； error!
/// ```
///
/// 您也可以使用不带任何值的 `dbg!()` 来仅在到达文件和行时打印它。
///
/// 最后，如果要 `dbg!(..)` 多个值，它将把它们视为一个元组 (并返回它) ：
///
/// ```
/// assert_eq!(dbg!(1usize, 2u32), (1, 2));
/// ```
///
/// 但是，遵循在宏调用中忽略尾部逗号的约定，带有尾部逗号的单个参数仍不会被视为元组。如果需要一个，可以直接使用一个 1 元组：
///
/// ```
/// assert_eq!(1, dbg!(1u32,)); // 尾部逗号被忽略
/// assert_eq!((1,), dbg!((1u32,))); // 1-tuple
/// ```
///
/// [stderr]: https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)
/// [`debug!`]: https://docs.rs/log/*/log/macro.debug.html
/// [`log`]: https://crates.io/crates/log
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[macro_export]
#[cfg_attr(not(test), rustc_diagnostic_item = "dbg_macro")]
#[stable(feature = "dbg_macro", since = "1.32.0")]
macro_rules! dbg {
    // NOTE: 我们不能使用 `concat!` 作为 `eprintln!` 的格式参数来生成静态字符串，因为 `file!` 可能包含 `{` 或 `$val` 表达式可能是一个块 (`{。
    // }`)，在这种情况下 `eprintln!` 的格式将不正确。
    //
    //
    () => {
        $crate::eprintln!("[{}:{}]", $crate::file!(), $crate::line!())
    };
    ($val:expr $(,)?) => {
        // 在此使用 `match` 是有意的，因为它会影响临时人员的生命周期 - https://stackoverflow.com/a/48732525/1063961
        //
        match $val {
            tmp => {
                $crate::eprintln!("[{}:{}] {} = {:#?}",
                    $crate::file!(), $crate::line!(), $crate::stringify!($val), &tmp);
                tmp
            }
        }
    };
    ($($val:expr),+ $(,)?) => {
        ($($crate::dbg!($val)),+,)
    };
}

#[cfg(test)]
macro_rules! assert_approx_eq {
    ($a:expr, $b:expr) => {{
        let (a, b) = (&$a, &$b);
        assert!((*a - *b).abs() < 1.0e-6, "{} is not approximately equal to {}", *a, *b);
    }};
}