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&mut DebugStruct<'_, '_>.debug_struct("Location")
91 .field("file", &self.file())
92 .field("line", &self.line)
93 .field(name:"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<'_> {}
310