core/panic/
location.rs

1use crate::cmp::Ordering;
2use crate::ffi::CStr;
3use crate::fmt;
4use crate::hash::{Hash, Hasher};
5use crate::marker::PhantomData;
6use crate::ptr::NonNull;
7
8/// A struct containing information about the location of a panic.
9///
10/// This structure is created by [`PanicHookInfo::location()`] and [`PanicInfo::location()`].
11///
12/// [`PanicInfo::location()`]: crate::panic::PanicInfo::location
13/// [`PanicHookInfo::location()`]: ../../std/panic/struct.PanicHookInfo.html#method.location
14///
15/// # Examples
16///
17/// ```should_panic
18/// use std::panic;
19///
20/// panic::set_hook(Box::new(|panic_info| {
21///     if let Some(location) = panic_info.location() {
22///         println!("panic occurred in file '{}' at line {}", location.file(), location.line());
23///     } else {
24///         println!("panic occurred but can't get location information...");
25///     }
26/// }));
27///
28/// panic!("Normal panic");
29/// ```
30///
31/// # Comparisons
32///
33/// Comparisons for equality and ordering are made in file, line, then column priority.
34/// Files are compared as strings, not `Path`, which could be unexpected.
35/// See [`Location::file`]'s documentation for more discussion.
36#[lang = "panic_location"]
37#[derive(Copy, Clone)]
38#[stable(feature = "panic_hooks", since = "1.10.0")]
39pub struct Location<'a> {
40    // A raw pointer is used rather than a reference because the pointer is valid for one more byte
41    // than the length stored in this pointer; the additional byte is the NUL-terminator used by
42    // `Location::file_as_c_str`.
43    filename: NonNull<str>,
44    line: u32,
45    col: u32,
46    _filename: PhantomData<&'a str>,
47}
48
49#[stable(feature = "panic_hooks", since = "1.10.0")]
50impl PartialEq for Location<'_> {
51    fn eq(&self, other: &Self) -> bool {
52        // Compare col / line first as they're cheaper to compare and more likely to differ,
53        // while not impacting the result.
54        self.col == other.col && self.line == other.line && self.file() == other.file()
55    }
56}
57
58#[stable(feature = "panic_hooks", since = "1.10.0")]
59impl Eq for Location<'_> {}
60
61#[stable(feature = "panic_hooks", since = "1.10.0")]
62impl Ord for Location<'_> {
63    fn cmp(&self, other: &Self) -> Ordering {
64        self.file()
65            .cmp(other.file())
66            .then_with(|| self.line.cmp(&other.line))
67            .then_with(|| self.col.cmp(&other.col))
68    }
69}
70
71#[stable(feature = "panic_hooks", since = "1.10.0")]
72impl PartialOrd for Location<'_> {
73    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
74        Some(self.cmp(other))
75    }
76}
77
78#[stable(feature = "panic_hooks", since = "1.10.0")]
79impl Hash for Location<'_> {
80    fn hash<H: Hasher>(&self, state: &mut H) {
81        self.file().hash(state);
82        self.line.hash(state);
83        self.col.hash(state);
84    }
85}
86
87#[stable(feature = "panic_hooks", since = "1.10.0")]
88impl fmt::Debug for Location<'_> {
89    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
90        f.debug_struct("Location")
91            .field("file", &self.file())
92            .field("line", &self.line)
93            .field("column", &self.col)
94            .finish()
95    }
96}
97
98impl<'a> Location<'a> {
99    /// Returns the source location of the caller of this function. If that function's caller is
100    /// annotated then its call location will be returned, and so on up the stack to the first call
101    /// within a non-tracked function body.
102    ///
103    /// # Examples
104    ///
105    /// ```standalone_crate
106    /// use std::panic::Location;
107    ///
108    /// /// ```
109    /// ///      |1        |11       |21       |31       |41
110    /// ///    +-|---------|---------|---------|---------|--------
111    /// /// 15 | #[track_caller]
112    /// /// 16 | fn new_location() -> &'static Location<'static> {
113    /// /// 17 |     Location::caller()
114    /// ///    |     ------------------| the value of this expression depends on the caller,
115    /// ///    |                       | since the function is marked #[track_caller]
116    /// /// 18 | }
117    /// /// ```
118    /// #[track_caller]
119    /// fn new_location() -> &'static Location<'static> {
120    ///     Location::caller()
121    /// }
122    ///
123    /// /// ```
124    /// ///      |1  |5    |11       |21       |31       |41       |51
125    /// ///    +-|---|-----|---------|---------|---------|---------|---
126    /// /// 29 | fn constant_location() -> &'static Location<'static> {
127    /// /// 30 |     new_location()
128    /// ///    |     ^ any invocation of constant_location() points here,
129    /// ///    |       no matter the location it is called from
130    /// /// 31 | }
131    /// /// ```
132    /// fn constant_location() -> &'static Location<'static> {
133    ///     new_location()
134    /// }
135    ///
136    /// fn main() {
137    ///     //      |1  |5    |11       |21       |31       |41       |51
138    ///     //    +-|---|-----|---------|---------|---------|---------|---
139    ///     // 29 | fn constant_location() -> &'static Location<'static> {
140    ///     // 30 |     new_location()
141    ///     //    |     ^ `let constant` points here
142    ///     // 31 | }
143    ///     let constant = constant_location();
144    ///     assert_eq!(constant.file(), file!());
145    ///     assert_eq!((constant.line(), constant.column()), (30, 5));
146    ///
147    ///     let constant_2 = constant_location();
148    ///     assert_eq!(
149    ///         (constant.file(), constant.line(), constant.column()),
150    ///         (constant_2.file(), constant_2.line(), constant_2.column())
151    ///     );
152    ///
153    ///     //      |1        |11  |16  |21       |31
154    ///     //    +-|---------|----|----|---------|------
155    ///     // 55 |     let here = new_location();
156    ///     //    |                ^ `let here` points here, as `new_location()` is the callsite
157    ///     // 56 |     assert_eq!(here.file(), file!());
158    ///     let here = new_location();
159    ///     assert_eq!(here.file(), file!());
160    ///     assert_eq!((here.line(), here.column()), (55, 16));
161    ///
162    ///     //      |1        |11       |21       ||32      |41       |51
163    ///     //    +-|---------|---------|---------||--------|---------|------
164    ///     // 64 |     let yet_another_location = new_location();
165    ///     //    |                                ^ `let yet_another_location` points here
166    ///     // 65 |     assert_eq!(here.file(), yet_another_location.file());
167    ///     let yet_another_location = new_location();
168    ///     assert_eq!(here.file(), yet_another_location.file());
169    ///     assert_ne!(
170    ///         (here.line(), here.column()),
171    ///         (yet_another_location.line(), yet_another_location.column())
172    ///     );
173    /// }
174    /// ```
175    #[must_use]
176    #[stable(feature = "track_caller", since = "1.46.0")]
177    #[rustc_const_stable(feature = "const_caller_location", since = "1.79.0")]
178    #[track_caller]
179    #[inline]
180    pub const fn caller() -> &'static Location<'static> {
181        crate::intrinsics::caller_location()
182    }
183
184    /// Returns the name of the source file from which the panic originated.
185    ///
186    /// # `&str`, not `&Path`
187    ///
188    /// The returned name refers to a source path on the compiling system, but it isn't valid to
189    /// represent this directly as a `&Path`. The compiled code may run on a different system with
190    /// a different `Path` implementation than the system providing the contents and this library
191    /// does not currently have a different "host path" type.
192    ///
193    /// The most surprising behavior occurs when "the same" file is reachable via multiple paths in
194    /// the module system (usually using the `#[path = "..."]` attribute or similar), which can
195    /// cause what appears to be identical code to return differing values from this function.
196    ///
197    /// # Cross-compilation
198    ///
199    /// This value is not suitable for passing to `Path::new` or similar constructors when the host
200    /// platform and target platform differ.
201    ///
202    /// # Examples
203    ///
204    /// ```should_panic
205    /// use std::panic;
206    ///
207    /// panic::set_hook(Box::new(|panic_info| {
208    ///     if let Some(location) = panic_info.location() {
209    ///         println!("panic occurred in file '{}'", location.file());
210    ///     } else {
211    ///         println!("panic occurred but can't get location information...");
212    ///     }
213    /// }));
214    ///
215    /// panic!("Normal panic");
216    /// ```
217    #[must_use]
218    #[stable(feature = "panic_hooks", since = "1.10.0")]
219    #[rustc_const_stable(feature = "const_location_fields", since = "1.79.0")]
220    pub const fn file(&self) -> &'a str {
221        // SAFETY: The filename is valid.
222        unsafe { self.filename.as_ref() }
223    }
224
225    /// Returns the name of the source file as a nul-terminated `CStr`.
226    ///
227    /// This is useful for interop with APIs that expect C/C++ `__FILE__` or
228    /// `std::source_location::file_name`, both of which return a nul-terminated `const char*`.
229    #[must_use]
230    #[inline]
231    #[stable(feature = "file_with_nul", since = "1.92.0")]
232    #[rustc_const_stable(feature = "file_with_nul", since = "1.92.0")]
233    pub const fn file_as_c_str(&self) -> &'a CStr {
234        let filename = self.filename.as_ptr();
235
236        // SAFETY: The filename is valid for `filename_len+1` bytes, so this addition can't
237        // overflow.
238        let cstr_len = unsafe { crate::mem::size_of_val_raw(filename).unchecked_add(1) };
239
240        // SAFETY: The filename is valid for `filename_len+1` bytes.
241        let slice = unsafe { crate::slice::from_raw_parts(filename.cast(), cstr_len) };
242
243        // SAFETY: The filename is guaranteed to have a trailing nul byte and no interior nul bytes.
244        unsafe { CStr::from_bytes_with_nul_unchecked(slice) }
245    }
246
247    /// Returns the line number from which the panic originated.
248    ///
249    /// # Examples
250    ///
251    /// ```should_panic
252    /// use std::panic;
253    ///
254    /// panic::set_hook(Box::new(|panic_info| {
255    ///     if let Some(location) = panic_info.location() {
256    ///         println!("panic occurred at line {}", location.line());
257    ///     } else {
258    ///         println!("panic occurred but can't get location information...");
259    ///     }
260    /// }));
261    ///
262    /// panic!("Normal panic");
263    /// ```
264    #[must_use]
265    #[stable(feature = "panic_hooks", since = "1.10.0")]
266    #[rustc_const_stable(feature = "const_location_fields", since = "1.79.0")]
267    #[inline]
268    pub const fn line(&self) -> u32 {
269        self.line
270    }
271
272    /// Returns the column from which the panic originated.
273    ///
274    /// # Examples
275    ///
276    /// ```should_panic
277    /// use std::panic;
278    ///
279    /// panic::set_hook(Box::new(|panic_info| {
280    ///     if let Some(location) = panic_info.location() {
281    ///         println!("panic occurred at column {}", location.column());
282    ///     } else {
283    ///         println!("panic occurred but can't get location information...");
284    ///     }
285    /// }));
286    ///
287    /// panic!("Normal panic");
288    /// ```
289    #[must_use]
290    #[stable(feature = "panic_col", since = "1.25.0")]
291    #[rustc_const_stable(feature = "const_location_fields", since = "1.79.0")]
292    #[inline]
293    pub const fn column(&self) -> u32 {
294        self.col
295    }
296}
297
298#[stable(feature = "panic_hook_display", since = "1.26.0")]
299impl fmt::Display for Location<'_> {
300    #[inline]
301    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
302        write!(formatter, "{}:{}:{}", self.file(), self.line, self.col)
303    }
304}
305
306#[stable(feature = "panic_hooks", since = "1.10.0")]
307unsafe impl Send for Location<'_> {}
308#[stable(feature = "panic_hooks", since = "1.10.0")]
309unsafe impl Sync for Location<'_> {}
core/panic/location.rs

core/panic/
location.rs
