From d275739c09f266479d6db388cbf55ba6ca791b9d Mon Sep 17 00:00:00 2001 From: Adam Perry Date: Sun, 21 Jun 2020 07:55:04 -0700 Subject: [PATCH 1/2] Derive common traits for panic::Location. Add documentation about the host/target behavior of Location::file. --- src/libcore/panic.rs | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/src/libcore/panic.rs b/src/libcore/panic.rs index c7009b76e8148..aa3625ac01953 100644 --- a/src/libcore/panic.rs +++ b/src/libcore/panic.rs @@ -173,8 +173,14 @@ impl fmt::Display for PanicInfo<'_> { /// /// panic!("Normal panic"); /// ``` +/// +/// # Comparisons +/// +/// Comparisons for equality and ordering are made in file, line, then column priority. Such +/// comparisons can occasionally have surprising results. See [`Location::file`]'s documentation for +/// more discussion. #[lang = "panic_location"] -#[derive(Debug)] +#[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] #[stable(feature = "panic_hooks", since = "1.10.0")] pub struct Location<'a> { file: &'a str, @@ -252,6 +258,22 @@ impl<'a> Location<'a> { /// Returns the name of the source file from which the panic originated. /// + /// # `&str`, not `&Path` + /// + /// The returned name refers to a source path on the compiling system, but it isn't valid to + /// represent this directly as a `&Path`. The compiled code may run on a different system with + /// a different `Path` implementation than the system providing the contents and this library + /// does not currently have a different "host path" type. + /// + /// The most surprising behavior occurs when "the same" file is reachable via multiple paths in + /// the module system (usually using the `#[path = "..."]` attribute or similar), which can + /// cause what appears to be identical code to return differing values from this function. + /// + /// # Cross-compilation + /// + /// This value is not suitable for passing to `Path::new` or similar constructors when the host + /// platform and target platform differ. + /// /// # Examples /// /// ```should_panic From 416dc4b978e5921cd0b20478a17f048dd378bdff Mon Sep 17 00:00:00 2001 From: Adam Perry Date: Sun, 19 Jul 2020 11:36:24 -0700 Subject: [PATCH 2/2] Clarify core::panic::Location's docs on ordering. Co-authored-by: Simon Sapin --- src/libcore/panic.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/libcore/panic.rs b/src/libcore/panic.rs index aa3625ac01953..94181084dbc6d 100644 --- a/src/libcore/panic.rs +++ b/src/libcore/panic.rs @@ -176,9 +176,9 @@ impl fmt::Display for PanicInfo<'_> { /// /// # Comparisons /// -/// Comparisons for equality and ordering are made in file, line, then column priority. Such -/// comparisons can occasionally have surprising results. See [`Location::file`]'s documentation for -/// more discussion. +/// Comparisons for equality and ordering are made in file, line, then column priority. +/// Files are compared as strings, not `Path`, which could be unexpected. +/// See [`Location::file`]'s documentation for more discussion. #[lang = "panic_location"] #[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] #[stable(feature = "panic_hooks", since = "1.10.0")]