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