Skip to content

Commit

Permalink
Derive common traits for panic::Location.
Browse files Browse the repository at this point in the history
Add documentation about the host/target behavior of Location::file.
  • Loading branch information
anp committed Jun 30, 2020
1 parent a1528c4 commit d275739
Showing 1 changed file with 23 additions and 1 deletion.
24 changes: 23 additions & 1 deletion src/libcore/panic.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit d275739

Please sign in to comment.