use crate::fmt;

/// 包含有关 panic 位置信息的结构体。
///
/// 该结构体由 [`PanicInfo::location()`] 创建。
///
/// [`PanicInfo::location()`]: crate::panic::PanicInfo::location
///
/// # Examples
///
/// ```should_panic
/// use std::panic;
///
/// panic::set_hook(Box::new(|panic_info| {
///     if let Some(location) = panic_info.location() {
///         println!("panic occurred in file '{}' at line {}", location.file(), location.line());
///     } else {
///         println!("panic occurred but can't get location information...");
///     }
/// }));
///
/// panic!("Normal panic");
/// ```
///
/// # Comparisons
///
/// 在文件，行和列优先级中进行相等性和顺序的比较。
/// 文件被比较为字符串，而不是 `Path`，这可能是意外的。
/// 有关更多讨论，请参见 [`Location::file`] 的文档。
#[lang = "panic_location"]
#[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[stable(feature = "panic_hooks", since = "1.10.0")]
pub struct Location<'a> {
    file: &'a str,
    line: u32,
    col: u32,
}

impl<'a> Location<'a> {
    /// 返回此函数的调用者的源位置。
    /// 如果该函数的调用者被注释，那么它的调用位置将被返回，以此类推，直到堆栈中第一个未被跟踪的函数体中的调用。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::panic::Location;
    ///
    /// /// 返回调用它的 [`Location`]。
    /// #[track_caller]
    /// fn get_caller_location() -> &'static Location<'static> {
    ///     Location::caller()
    /// }
    ///
    /// /// 从此函数的定义中返回 [`Location`]。
    /// fn get_just_one_location() -> &'static Location<'static> {
    ///     get_caller_location()
    /// }
    ///
    /// let fixed_location = get_just_one_location();
    /// assert_eq!(fixed_location.file(), file!());
    /// assert_eq!(fixed_location.line(), 14);
    /// assert_eq!(fixed_location.column(), 5);
    ///
    /// // 在不同的位置运行相同的未跟踪函数会得到相同的结果
    /// let second_fixed_location = get_just_one_location();
    /// assert_eq!(fixed_location.file(), second_fixed_location.file());
    /// assert_eq!(fixed_location.line(), second_fixed_location.line());
    /// assert_eq!(fixed_location.column(), second_fixed_location.column());
    ///
    /// let this_location = get_caller_location();
    /// assert_eq!(this_location.file(), file!());
    /// assert_eq!(this_location.line(), 28);
    /// assert_eq!(this_location.column(), 21);
    ///
    /// // 在其他位置运行跟踪的函数会产生不同的值
    /// let another_location = get_caller_location();
    /// assert_eq!(this_location.file(), another_location.file());
    /// assert_ne!(this_location.line(), another_location.line());
    /// assert_ne!(this_location.column(), another_location.column());
    /// ```
    #[must_use]
    #[stable(feature = "track_caller", since = "1.46.0")]
    #[rustc_const_unstable(feature = "const_caller_location", issue = "76156")]
    #[track_caller]
    #[inline]
    pub const fn caller() -> &'static Location<'static> {
        crate::intrinsics::caller_location()
    }

    /// 返回 panic 源自的源文件的名称。
    ///
    /// # `&str`，不是 `&Path`
    ///
    /// 返回的名称指向编译系统上的源路径，但是将其直接表示为 `&Path` 是无效的。
    /// 与提供内容的系统相比，编译后的代码可以在具有不同 `Path` 实现的不同系统上运行，并且此库当前没有不同的 "host path" 类型。
    ///
    /// 当通过模块系统中的多个路径可访问 "the same" 文件时 (通常使用 `#[path = "..."]` 属性或类似属性)，会发生最令人惊讶的行为，这可能导致看似相同的代码返回与此函数不同的值。
    ///
    ///
    /// # Cross-compilation
    ///
    /// 当主机平台和目标平台不同时，此值不适合传递给 `Path::new` 或类似的构造函数。
    ///
    /// # Examples
    ///
    /// ```should_panic
    /// use std::panic;
    ///
    /// panic::set_hook(Box::new(|panic_info| {
    ///     if let Some(location) = panic_info.location() {
    ///         println!("panic occurred in file '{}'", location.file());
    ///     } else {
    ///         println!("panic occurred but can't get location information...");
    ///     }
    /// }));
    ///
    /// panic!("Normal panic");
    /// ```
    ///
    ///
    ///
    ///
    #[must_use]
    #[stable(feature = "panic_hooks", since = "1.10.0")]
    #[rustc_const_unstable(feature = "const_location_fields", issue = "102911")]
    #[inline]
    pub const fn file(&self) -> &str {
        self.file
    }

    /// 返回 panic 起源的行号。
    ///
    /// # Examples
    ///
    /// ```should_panic
    /// use std::panic;
    ///
    /// panic::set_hook(Box::new(|panic_info| {
    ///     if let Some(location) = panic_info.location() {
    ///         println!("panic occurred at line {}", location.line());
    ///     } else {
    ///         println!("panic occurred but can't get location information...");
    ///     }
    /// }));
    ///
    /// panic!("Normal panic");
    /// ```
    #[must_use]
    #[stable(feature = "panic_hooks", since = "1.10.0")]
    #[rustc_const_unstable(feature = "const_location_fields", issue = "102911")]
    #[inline]
    pub const fn line(&self) -> u32 {
        self.line
    }

    /// 返回 panic 起源的列。
    ///
    /// # Examples
    ///
    /// ```should_panic
    /// use std::panic;
    ///
    /// panic::set_hook(Box::new(|panic_info| {
    ///     if let Some(location) = panic_info.location() {
    ///         println!("panic occurred at column {}", location.column());
    ///     } else {
    ///         println!("panic occurred but can't get location information...");
    ///     }
    /// }));
    ///
    /// panic!("Normal panic");
    /// ```
    #[must_use]
    #[stable(feature = "panic_col", since = "1.25.0")]
    #[rustc_const_unstable(feature = "const_location_fields", issue = "102911")]
    #[inline]
    pub const fn column(&self) -> u32 {
        self.col
    }
}

#[unstable(
    feature = "panic_internals",
    reason = "internal details of the implementation of the `panic!` and related macros",
    issue = "none"
)]
impl<'a> Location<'a> {
    #[doc(hidden)]
    pub const fn internal_constructor(file: &'a str, line: u32, col: u32) -> Self {
        Location { file, line, col }
    }
}

#[stable(feature = "panic_hook_display", since = "1.26.0")]
impl fmt::Display for Location<'_> {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "{}:{}:{}", self.file, self.line, self.col)
    }
}