Auto merge of #73583 - anp:location-eq, r=dtolnay

Derive common traits for panic::Location.

Now that `#[track_caller]` is on track to stabilize, one of the roughest edges of working with it is the fact that you can't do much with `Location` except turn it back into a `(&str, u32, u32)`. Which makes sense because the type was defined around the panic machinery originally passing around that tuple (it has the same layout as Location even).

This PR derives common traits for the type in accordance with the [API guidelines](https://rust-lang.github.io/api-guidelines/interoperability.html#types-eagerly-implement-common-traits-c-common-traits) (those apply to core, right?).

There's a risk here, e.g. if we ever change the representation of `Location` in a way that makes it harder to implement `Ord`, we might not be able to make that change in a backwards-compatible way. I don't think there's any other compatibility hazard here, as the only changes we currently imagine for the type are to add end fields.

cc @rust-lang/libs

diff --git a/src/libcore/panic.rs b/src/libcore/panic.rs
index 543aa969330aedbf8056a4dbf140a4ba815677f9..316ecafe572c54d569f99a2b6d8731cf7fe6b5aa 100644 (file)
--- a/src/libcore/panic.rs
+++ b/src/libcore/panic.rs
@@ -173,8 +173,14 @@ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
 ///
 /// panic!("Normal panic");
 /// ```
+///
+/// # Comparisons
+///
+/// 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(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,
@@ -246,6 +252,22 @@ pub const fn internal_constructor(file: &'a str, line: u32, col: u32) -> Self {
 
     /// 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