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