1 | use crate::fmt; |
2 | |
3 | /// A struct containing information about the location of a panic. |
4 | /// |
5 | /// This structure is created by [`PanicHookInfo::location()`] and [`PanicInfo::location()`]. |
6 | /// |
7 | /// [`PanicInfo::location()`]: crate::panic::PanicInfo::location |
8 | /// [`PanicHookInfo::location()`]: ../../std/panic/struct.PanicHookInfo.html#method.location |
9 | /// |
10 | /// # Examples |
11 | /// |
12 | /// ```should_panic |
13 | /// use std::panic; |
14 | /// |
15 | /// panic::set_hook(Box::new(|panic_info| { |
16 | /// if let Some(location) = panic_info.location() { |
17 | /// println!("panic occurred in file '{}' at line {}" , location.file(), location.line()); |
18 | /// } else { |
19 | /// println!("panic occurred but can't get location information..." ); |
20 | /// } |
21 | /// })); |
22 | /// |
23 | /// panic!("Normal panic" ); |
24 | /// ``` |
25 | /// |
26 | /// # Comparisons |
27 | /// |
28 | /// Comparisons for equality and ordering are made in file, line, then column priority. |
29 | /// Files are compared as strings, not `Path`, which could be unexpected. |
30 | /// See [`Location::file`]'s documentation for more discussion. |
31 | #[lang = "panic_location" ] |
32 | #[derive (Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] |
33 | #[stable (feature = "panic_hooks" , since = "1.10.0" )] |
34 | pub struct Location<'a> { |
35 | file: &'a str, |
36 | line: u32, |
37 | col: u32, |
38 | } |
39 | |
40 | impl<'a> Location<'a> { |
41 | /// Returns the source location of the caller of this function. If that function's caller is |
42 | /// annotated then its call location will be returned, and so on up the stack to the first call |
43 | /// within a non-tracked function body. |
44 | /// |
45 | /// # Examples |
46 | /// |
47 | /// ```standalone_crate |
48 | /// use std::panic::Location; |
49 | /// |
50 | /// /// Returns the [`Location`] at which it is called. |
51 | /// #[track_caller] |
52 | /// fn get_caller_location() -> &'static Location<'static> { |
53 | /// Location::caller() |
54 | /// } |
55 | /// |
56 | /// /// Returns a [`Location`] from within this function's definition. |
57 | /// fn get_just_one_location() -> &'static Location<'static> { |
58 | /// get_caller_location() |
59 | /// } |
60 | /// |
61 | /// let fixed_location = get_just_one_location(); |
62 | /// assert_eq!(fixed_location.file(), file!()); |
63 | /// assert_eq!(fixed_location.line(), 14); |
64 | /// assert_eq!(fixed_location.column(), 5); |
65 | /// |
66 | /// // running the same untracked function in a different location gives us the same result |
67 | /// let second_fixed_location = get_just_one_location(); |
68 | /// assert_eq!(fixed_location.file(), second_fixed_location.file()); |
69 | /// assert_eq!(fixed_location.line(), second_fixed_location.line()); |
70 | /// assert_eq!(fixed_location.column(), second_fixed_location.column()); |
71 | /// |
72 | /// let this_location = get_caller_location(); |
73 | /// assert_eq!(this_location.file(), file!()); |
74 | /// assert_eq!(this_location.line(), 28); |
75 | /// assert_eq!(this_location.column(), 21); |
76 | /// |
77 | /// // running the tracked function in a different location produces a different value |
78 | /// let another_location = get_caller_location(); |
79 | /// assert_eq!(this_location.file(), another_location.file()); |
80 | /// assert_ne!(this_location.line(), another_location.line()); |
81 | /// assert_ne!(this_location.column(), another_location.column()); |
82 | /// ``` |
83 | #[must_use ] |
84 | #[stable (feature = "track_caller" , since = "1.46.0" )] |
85 | #[rustc_const_stable (feature = "const_caller_location" , since = "1.79.0" )] |
86 | #[track_caller ] |
87 | #[inline ] |
88 | pub const fn caller() -> &'static Location<'static> { |
89 | crate::intrinsics::caller_location() |
90 | } |
91 | |
92 | /// Returns the name of the source file from which the panic originated. |
93 | /// |
94 | /// # `&str`, not `&Path` |
95 | /// |
96 | /// The returned name refers to a source path on the compiling system, but it isn't valid to |
97 | /// represent this directly as a `&Path`. The compiled code may run on a different system with |
98 | /// a different `Path` implementation than the system providing the contents and this library |
99 | /// does not currently have a different "host path" type. |
100 | /// |
101 | /// The most surprising behavior occurs when "the same" file is reachable via multiple paths in |
102 | /// the module system (usually using the `#[path = "..."]` attribute or similar), which can |
103 | /// cause what appears to be identical code to return differing values from this function. |
104 | /// |
105 | /// # Cross-compilation |
106 | /// |
107 | /// This value is not suitable for passing to `Path::new` or similar constructors when the host |
108 | /// platform and target platform differ. |
109 | /// |
110 | /// # Examples |
111 | /// |
112 | /// ```should_panic |
113 | /// use std::panic; |
114 | /// |
115 | /// panic::set_hook(Box::new(|panic_info| { |
116 | /// if let Some(location) = panic_info.location() { |
117 | /// println!("panic occurred in file '{}'" , location.file()); |
118 | /// } else { |
119 | /// println!("panic occurred but can't get location information..." ); |
120 | /// } |
121 | /// })); |
122 | /// |
123 | /// panic!("Normal panic" ); |
124 | /// ``` |
125 | #[must_use ] |
126 | #[stable (feature = "panic_hooks" , since = "1.10.0" )] |
127 | #[rustc_const_stable (feature = "const_location_fields" , since = "1.79.0" )] |
128 | #[inline ] |
129 | pub const fn file(&self) -> &str { |
130 | self.file |
131 | } |
132 | |
133 | /// Returns the line number from which the panic originated. |
134 | /// |
135 | /// # Examples |
136 | /// |
137 | /// ```should_panic |
138 | /// use std::panic; |
139 | /// |
140 | /// panic::set_hook(Box::new(|panic_info| { |
141 | /// if let Some(location) = panic_info.location() { |
142 | /// println!("panic occurred at line {}" , location.line()); |
143 | /// } else { |
144 | /// println!("panic occurred but can't get location information..." ); |
145 | /// } |
146 | /// })); |
147 | /// |
148 | /// panic!("Normal panic" ); |
149 | /// ``` |
150 | #[must_use ] |
151 | #[stable (feature = "panic_hooks" , since = "1.10.0" )] |
152 | #[rustc_const_stable (feature = "const_location_fields" , since = "1.79.0" )] |
153 | #[inline ] |
154 | pub const fn line(&self) -> u32 { |
155 | self.line |
156 | } |
157 | |
158 | /// Returns the column from which the panic originated. |
159 | /// |
160 | /// # Examples |
161 | /// |
162 | /// ```should_panic |
163 | /// use std::panic; |
164 | /// |
165 | /// panic::set_hook(Box::new(|panic_info| { |
166 | /// if let Some(location) = panic_info.location() { |
167 | /// println!("panic occurred at column {}" , location.column()); |
168 | /// } else { |
169 | /// println!("panic occurred but can't get location information..." ); |
170 | /// } |
171 | /// })); |
172 | /// |
173 | /// panic!("Normal panic" ); |
174 | /// ``` |
175 | #[must_use ] |
176 | #[stable (feature = "panic_col" , since = "1.25.0" )] |
177 | #[rustc_const_stable (feature = "const_location_fields" , since = "1.79.0" )] |
178 | #[inline ] |
179 | pub const fn column(&self) -> u32 { |
180 | self.col |
181 | } |
182 | } |
183 | |
184 | #[unstable ( |
185 | feature = "panic_internals" , |
186 | reason = "internal details of the implementation of the `panic!` and related macros" , |
187 | issue = "none" |
188 | )] |
189 | impl<'a> Location<'a> { |
190 | #[doc (hidden)] |
191 | pub const fn internal_constructor(file: &'a str, line: u32, col: u32) -> Self { |
192 | Location { file, line, col } |
193 | } |
194 | } |
195 | |
196 | #[stable (feature = "panic_hook_display" , since = "1.26.0" )] |
197 | impl fmt::Display for Location<'_> { |
198 | #[inline ] |
199 | fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { |
200 | write!(formatter, " {}: {}: {}" , self.file, self.line, self.col) |
201 | } |
202 | } |
203 | |