#![allow(missing_debug_implementations)]
#![unstable(feature = "fmt_internals", reason = "internal to format_args!", issue = "none")]

//! 这些是 format_args!() 使用的 lang 项。

use super::*;

#[lang = "format_placeholder"]
#[derive(Copy, Clone)]
pub struct Placeholder {
    pub position: usize,
    pub fill: char,
    pub align: Alignment,
    pub flags: u32,
    pub precision: Count,
    pub width: Count,
}

impl Placeholder {
    #[inline(always)]
    pub const fn new(
        position: usize,
        fill: char,
        align: Alignment,
        flags: u32,
        precision: Count,
        width: Count,
    ) -> Self {
        Self { position, fill, align, flags, precision, width }
    }
}

#[lang = "format_alignment"]
#[derive(Copy, Clone, PartialEq, Eq)]
pub enum Alignment {
    Left,
    Right,
    Center,
    Unknown,
}

/// 由 [width](https://doc.rust-lang.org/std/fmt/#width) 和 [precision](https://doc.rust-lang.org/std/fmt/#precision) 说明符使用。
///
#[lang = "format_count"]
#[derive(Copy, Clone)]
pub enum Count {
    /// 用字面量数字指定，存储该值
    Is(usize),
    /// 使用 `$` 和 `*` 语法指定，将索引存储到 `args`
    Param(usize),
    /// 未标明
    Implied,
}

// 这需要匹配 compiler/rustc_ast_lowering/src/format.rs 中标志的顺序。
#[derive(Copy, Clone)]
pub(super) enum Flag {
    SignPlus,
    SignMinus,
    Alternate,
    SignAwareZeroPad,
    DebugLowerHex,
    DebugUpperHex,
}

/// 这个结构体代表泛型 "argument"，被 format_args!() 拿走了。
/// 它包含一个用于格式化给定值的函数。
/// 在编译时，请确保函数和值具有正确的类型，然后使用此结构体将参数规范化为一种类型。
///
///
/// 参数本质上是优化的部分应用的格式化函数，等效于 `exists T.(&T, fn(&T, &mut Formatter<'_>) -> Result`。
///
#[lang = "format_argument"]
#[derive(Copy, Clone)]
pub struct Argument<'a> {
    value: &'a Opaque,
    formatter: fn(&Opaque, &mut Formatter<'_>) -> Result,
}

#[rustc_diagnostic_item = "ArgumentMethods"]
impl<'a> Argument<'a> {
    #[inline(always)]
    fn new<'b, T>(x: &'b T, f: fn(&T, &mut Formatter<'_>) -> Result) -> Argument<'b> {
        // SAFETY: `mem::transmute(x)` 是安全的，因为
        //     1. `&'b T` 保持它起源于 `'b` 的生命周期 (以便没有无限的生命周期)
        //     2.
        //     `&'b T` 和 `&'b Opaque` 具有相同的内存布局 (当 `T` 是 `Sized` 时，就像这里一样) `mem::transmute(f)` 是安全的，因为 `fn(&T, &mut Formatter<'_>) -> Result` 和 `fn(&Opaque, &mut Formatter<'_>) -> Result` 具有相同的 ABI (只要 `T` 是 `Sized`)
        //
        //
        //
        //
        unsafe { Argument { formatter: mem::transmute(f), value: mem::transmute(x) } }
    }

    #[inline(always)]
    pub fn new_display<'b, T: Display>(x: &'b T) -> Argument<'_> {
        Self::new(x, Display::fmt)
    }
    #[inline(always)]
    pub fn new_debug<'b, T: Debug>(x: &'b T) -> Argument<'_> {
        Self::new(x, Debug::fmt)
    }
    #[inline(always)]
    pub fn new_octal<'b, T: Octal>(x: &'b T) -> Argument<'_> {
        Self::new(x, Octal::fmt)
    }
    #[inline(always)]
    pub fn new_lower_hex<'b, T: LowerHex>(x: &'b T) -> Argument<'_> {
        Self::new(x, LowerHex::fmt)
    }
    #[inline(always)]
    pub fn new_upper_hex<'b, T: UpperHex>(x: &'b T) -> Argument<'_> {
        Self::new(x, UpperHex::fmt)
    }
    #[inline(always)]
    pub fn new_pointer<'b, T: Pointer>(x: &'b T) -> Argument<'_> {
        Self::new(x, Pointer::fmt)
    }
    #[inline(always)]
    pub fn new_binary<'b, T: Binary>(x: &'b T) -> Argument<'_> {
        Self::new(x, Binary::fmt)
    }
    #[inline(always)]
    pub fn new_lower_exp<'b, T: LowerExp>(x: &'b T) -> Argument<'_> {
        Self::new(x, LowerExp::fmt)
    }
    #[inline(always)]
    pub fn new_upper_exp<'b, T: UpperExp>(x: &'b T) -> Argument<'_> {
        Self::new(x, UpperExp::fmt)
    }
    #[inline(always)]
    pub fn from_usize(x: &usize) -> Argument<'_> {
        Self::new(x, USIZE_MARKER)
    }

    #[inline(always)]
    pub(super) fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        (self.formatter)(self.value, f)
    }

    #[inline(always)]
    pub(super) fn as_usize(&self) -> Option<usize> {
        // 我们在这里有点双关: USIZE_MARKER 只接受一个 &usize，但格式化程序需要接受一个 &Opaque。
        // 可以理解的是，Rust 认为如果函数指针没有相同的签名，我们就不应该比较它们，所以我们转换成 usizes，告诉它我们只是想比较地址。
        //
        //
        if self.formatter as usize == USIZE_MARKER as usize {
            // SAFETY: 仅当值是 usize 时，才将 `formatter` 字段设置为 USIZE_MARKER，因此这是安全的
            //
            Some(unsafe { *(self.value as *const _ as *const usize) })
        } else {
            None
        }
    }

    /// 在内联后所有参数都消失时由 `format_args` 使用，当使用 `&[]` 时会错误地允许更大的生命周期。
    ///
    ///
    /// 如果没有格式参数内联，这将失败，并且内联参数时应该没有什么不同:
    ///
    /// ```compile_fail,E0716
    /// let f = format_args!("{}", "a");
    /// println!("{f}");
    /// ```
    ///
    #[inline(always)]
    pub fn none() -> [Self; 0] {
        []
    }
}

/// 这个结构体代表了构建 `Arguments` 的不安全性。
/// 它的存在，而不是一个不安全的函数，是为了简化 `format_args!(..)` 的扩展，并缩小 `unsafe` 块的作用域。
///
#[lang = "format_unsafe_arg"]
pub struct UnsafeArg {
    _private: (),
}

impl UnsafeArg {
    /// 请参见 `UnsafeArg` 的文档，需要知道何时可以安全地创建和使用 `UnsafeArg`。
    ///
    #[inline(always)]
    pub unsafe fn new() -> Self {
        Self { _private: () }
    }
}

extern "C" {
    type Opaque;
}

// 这样可以确保格式基础结构中与 indices/counts 关联的函数指针具有单个稳定值。
//
// 请注意，这样定义的函数将是不正确的，因为该函数始终会被标记为 unnamed_addr，并且当前的状态会降低到 LLVM IR，因此它们的地址对于 LLVM 并不重要，因此 as_usize 强制转换可能会被错误编译。
//
// 在实践中，我们绝不会在未使用的包含数据上调用 as_usize (作为 formatting 参数的静态生成的问题)，因此，这仅仅是一项额外的检查。
//
// 我们主要是要确保 `USIZE_MARKER` 处的函数指针具有对应于 *only* 的地址，该地址也将 `&usize` 作为它的第一个参数。
// 这里的 read_volatile 确保我们可以安全地从传递的引用中准备出 usize，并且此地址不指向未使用的接受函数。
//
//
//
//
//
//
//
static USIZE_MARKER: fn(&usize, &mut Formatter<'_>) -> Result = |ptr, _| {
    // SAFETY: ptr 是引用
    let _v: usize = unsafe { crate::ptr::read_volatile(ptr) };
    loop {}
};