]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | //! Standard library macros |
2 | //! | |
3dfed10e | 3 | //! This module contains a set of macros which are exported from the standard |
1a4d82fc JJ |
4 | //! library. Each macro is available for use when linking against the standard |
5 | //! library. | |
970d7e83 | 6 | |
3dfed10e | 7 | #[doc(include = "../../core/src/macros/panic.md")] |
dfeec247 XL |
8 | #[macro_export] |
9 | #[stable(feature = "rust1", since = "1.0.0")] | |
10 | #[allow_internal_unstable(libstd_sys_internals)] | |
fc512014 | 11 | #[cfg_attr(not(any(bootstrap, test)), rustc_diagnostic_item = "std_panic_macro")] |
dfeec247 XL |
12 | macro_rules! panic { |
13 | () => ({ $crate::panic!("explicit panic") }); | |
29967ef6 | 14 | ($msg:expr $(,)?) => ({ $crate::rt::begin_panic($msg) }); |
dfeec247 XL |
15 | ($fmt:expr, $($arg:tt)+) => ({ |
16 | $crate::rt::begin_panic_fmt(&$crate::format_args!($fmt, $($arg)+)) | |
1a4d82fc JJ |
17 | }); |
18 | } | |
19 | ||
532ac7d7 | 20 | /// Prints to the standard output. |
c34b1796 | 21 | /// |
ea8adc8c | 22 | /// Equivalent to the [`println!`] macro except that a newline is not printed at |
1a4d82fc | 23 | /// the end of the message. |
c34b1796 AL |
24 | /// |
25 | /// Note that stdout is frequently line-buffered by default so it may be | |
ea8adc8c | 26 | /// necessary to use [`io::stdout().flush()`][flush] to ensure the output is emitted |
c34b1796 | 27 | /// immediately. |
e9174d1e | 28 | /// |
9fa01778 | 29 | /// Use `print!` only for the primary output of your program. Use |
ea8adc8c XL |
30 | /// [`eprint!`] instead to print error and progress messages. |
31 | /// | |
3dfed10e | 32 | /// [flush]: crate::io::Write::flush |
7cac9316 | 33 | /// |
b039eaaf SL |
34 | /// # Panics |
35 | /// | |
36 | /// Panics if writing to `io::stdout()` fails. | |
37 | /// | |
e9174d1e SL |
38 | /// # Examples |
39 | /// | |
40 | /// ``` | |
41 | /// use std::io::{self, Write}; | |
42 | /// | |
43 | /// print!("this "); | |
44 | /// print!("will "); | |
45 | /// print!("be "); | |
46 | /// print!("on "); | |
47 | /// print!("the "); | |
48 | /// print!("same "); | |
49 | /// print!("line "); | |
50 | /// | |
51 | /// io::stdout().flush().unwrap(); | |
52 | /// | |
53 | /// print!("this string has a newline, why not choose println! instead?\n"); | |
54 | /// | |
55 | /// io::stdout().flush().unwrap(); | |
56 | /// ``` | |
1a4d82fc | 57 | #[macro_export] |
85aaf69f | 58 | #[stable(feature = "rust1", since = "1.0.0")] |
532ac7d7 | 59 | #[allow_internal_unstable(print_internals)] |
1a4d82fc | 60 | macro_rules! print { |
e1599b0c | 61 | ($($arg:tt)*) => ($crate::io::_print($crate::format_args!($($arg)*))); |
1a4d82fc | 62 | } |
970d7e83 | 63 | |
532ac7d7 | 64 | /// Prints to the standard output, with a newline. |
ea8adc8c XL |
65 | /// |
66 | /// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone | |
416331ca | 67 | /// (no additional CARRIAGE RETURN (`\r`/`U+000D`)). |
1a4d82fc | 68 | /// |
ea8adc8c XL |
69 | /// Use the [`format!`] syntax to write data to the standard output. |
70 | /// See [`std::fmt`] for more information. | |
1a4d82fc | 71 | /// |
9fa01778 | 72 | /// Use `println!` only for the primary output of your program. Use |
ea8adc8c | 73 | /// [`eprintln!`] instead to print error and progress messages. |
7cac9316 | 74 | /// |
3dfed10e XL |
75 | /// [`std::fmt`]: crate::fmt |
76 | /// | |
b039eaaf SL |
77 | /// # Panics |
78 | /// | |
3dfed10e XL |
79 | /// Panics if writing to [`io::stdout`] fails. |
80 | /// | |
81 | /// [`io::stdout`]: crate::io::stdout | |
b039eaaf | 82 | /// |
c34b1796 | 83 | /// # Examples |
1a4d82fc JJ |
84 | /// |
85 | /// ``` | |
32a655c1 | 86 | /// println!(); // prints just a newline |
1a4d82fc JJ |
87 | /// println!("hello there!"); |
88 | /// println!("format {} arguments", "some"); | |
89 | /// ``` | |
90 | #[macro_export] | |
85aaf69f | 91 | #[stable(feature = "rust1", since = "1.0.0")] |
532ac7d7 | 92 | #[allow_internal_unstable(print_internals, format_args_nl)] |
1a4d82fc | 93 | macro_rules! println { |
48663c56 | 94 | () => ($crate::print!("\n")); |
8faf50e0 | 95 | ($($arg:tt)*) => ({ |
e1599b0c | 96 | $crate::io::_print($crate::format_args_nl!($($arg)*)); |
8faf50e0 | 97 | }) |
1a4d82fc JJ |
98 | } |
99 | ||
532ac7d7 | 100 | /// Prints to the standard error. |
7cac9316 | 101 | /// |
ea8adc8c | 102 | /// Equivalent to the [`print!`] macro, except that output goes to |
3dfed10e | 103 | /// [`io::stderr`] instead of [`io::stdout`]. See [`print!`] for |
7cac9316 XL |
104 | /// example usage. |
105 | /// | |
9fa01778 | 106 | /// Use `eprint!` only for error and progress messages. Use `print!` |
7cac9316 XL |
107 | /// instead for the primary output of your program. |
108 | /// | |
3dfed10e XL |
109 | /// [`io::stderr`]: crate::io::stderr |
110 | /// [`io::stdout`]: crate::io::stdout | |
ea8adc8c | 111 | /// |
7cac9316 XL |
112 | /// # Panics |
113 | /// | |
114 | /// Panics if writing to `io::stderr` fails. | |
ea8adc8c XL |
115 | /// |
116 | /// # Examples | |
117 | /// | |
118 | /// ``` | |
119 | /// eprint!("Error: Could not complete task"); | |
120 | /// ``` | |
7cac9316 XL |
121 | #[macro_export] |
122 | #[stable(feature = "eprint", since = "1.19.0")] | |
532ac7d7 | 123 | #[allow_internal_unstable(print_internals)] |
7cac9316 | 124 | macro_rules! eprint { |
e1599b0c | 125 | ($($arg:tt)*) => ($crate::io::_eprint($crate::format_args!($($arg)*))); |
7cac9316 XL |
126 | } |
127 | ||
532ac7d7 | 128 | /// Prints to the standard error, with a newline. |
7cac9316 | 129 | /// |
ea8adc8c | 130 | /// Equivalent to the [`println!`] macro, except that output goes to |
3dfed10e | 131 | /// [`io::stderr`] instead of [`io::stdout`]. See [`println!`] for |
7cac9316 XL |
132 | /// example usage. |
133 | /// | |
9fa01778 | 134 | /// Use `eprintln!` only for error and progress messages. Use `println!` |
7cac9316 XL |
135 | /// instead for the primary output of your program. |
136 | /// | |
3dfed10e XL |
137 | /// [`io::stderr`]: crate::io::stderr |
138 | /// [`io::stdout`]: crate::io::stdout | |
ea8adc8c | 139 | /// |
7cac9316 XL |
140 | /// # Panics |
141 | /// | |
142 | /// Panics if writing to `io::stderr` fails. | |
ea8adc8c XL |
143 | /// |
144 | /// # Examples | |
145 | /// | |
146 | /// ``` | |
147 | /// eprintln!("Error: Could not complete task"); | |
148 | /// ``` | |
7cac9316 XL |
149 | #[macro_export] |
150 | #[stable(feature = "eprint", since = "1.19.0")] | |
532ac7d7 | 151 | #[allow_internal_unstable(print_internals, format_args_nl)] |
7cac9316 | 152 | macro_rules! eprintln { |
48663c56 | 153 | () => ($crate::eprint!("\n")); |
8faf50e0 | 154 | ($($arg:tt)*) => ({ |
e1599b0c | 155 | $crate::io::_eprint($crate::format_args_nl!($($arg)*)); |
8faf50e0 XL |
156 | }) |
157 | } | |
158 | ||
532ac7d7 XL |
159 | /// Prints and returns the value of a given expression for quick and dirty |
160 | /// debugging. | |
161 | /// | |
162 | /// An example: | |
0bf4aa26 XL |
163 | /// |
164 | /// ```rust | |
0bf4aa26 XL |
165 | /// let a = 2; |
166 | /// let b = dbg!(a * 2) + 1; | |
a1dfa0c6 | 167 | /// // ^-- prints: [src/main.rs:2] a * 2 = 4 |
0bf4aa26 XL |
168 | /// assert_eq!(b, 5); |
169 | /// ``` | |
170 | /// | |
171 | /// The macro works by using the `Debug` implementation of the type of | |
172 | /// the given expression to print the value to [stderr] along with the | |
173 | /// source location of the macro invocation as well as the source code | |
174 | /// of the expression. | |
175 | /// | |
176 | /// Invoking the macro on an expression moves and takes ownership of it | |
177 | /// before returning the evaluated expression unchanged. If the type | |
178 | /// of the expression does not implement `Copy` and you don't want | |
179 | /// to give up ownership, you can instead borrow with `dbg!(&expr)` | |
180 | /// for some expression `expr`. | |
181 | /// | |
532ac7d7 XL |
182 | /// The `dbg!` macro works exactly the same in release builds. |
183 | /// This is useful when debugging issues that only occur in release | |
184 | /// builds or when debugging in release mode is significantly faster. | |
185 | /// | |
0bf4aa26 | 186 | /// Note that the macro is intended as a debugging tool and therefore you |
74b04a01 | 187 | /// should avoid having uses of it in version control for long periods. |
0bf4aa26 | 188 | /// Use cases involving debug output that should be added to version control |
532ac7d7 | 189 | /// are better served by macros such as [`debug!`] from the [`log`] crate. |
0bf4aa26 XL |
190 | /// |
191 | /// # Stability | |
192 | /// | |
193 | /// The exact output printed by this macro should not be relied upon | |
194 | /// and is subject to future changes. | |
195 | /// | |
196 | /// # Panics | |
197 | /// | |
198 | /// Panics if writing to `io::stderr` fails. | |
199 | /// | |
200 | /// # Further examples | |
201 | /// | |
202 | /// With a method call: | |
203 | /// | |
204 | /// ```rust | |
0bf4aa26 XL |
205 | /// fn foo(n: usize) { |
206 | /// if let Some(_) = dbg!(n.checked_sub(4)) { | |
207 | /// // ... | |
208 | /// } | |
209 | /// } | |
210 | /// | |
211 | /// foo(3) | |
212 | /// ``` | |
213 | /// | |
214 | /// This prints to [stderr]: | |
215 | /// | |
216 | /// ```text,ignore | |
217 | /// [src/main.rs:4] n.checked_sub(4) = None | |
218 | /// ``` | |
219 | /// | |
220 | /// Naive factorial implementation: | |
221 | /// | |
222 | /// ```rust | |
0bf4aa26 XL |
223 | /// fn factorial(n: u32) -> u32 { |
224 | /// if dbg!(n <= 1) { | |
225 | /// dbg!(1) | |
226 | /// } else { | |
227 | /// dbg!(n * factorial(n - 1)) | |
228 | /// } | |
229 | /// } | |
230 | /// | |
231 | /// dbg!(factorial(4)); | |
232 | /// ``` | |
233 | /// | |
234 | /// This prints to [stderr]: | |
235 | /// | |
236 | /// ```text,ignore | |
237 | /// [src/main.rs:3] n <= 1 = false | |
238 | /// [src/main.rs:3] n <= 1 = false | |
239 | /// [src/main.rs:3] n <= 1 = false | |
240 | /// [src/main.rs:3] n <= 1 = true | |
241 | /// [src/main.rs:4] 1 = 1 | |
242 | /// [src/main.rs:5] n * factorial(n - 1) = 2 | |
243 | /// [src/main.rs:5] n * factorial(n - 1) = 6 | |
244 | /// [src/main.rs:5] n * factorial(n - 1) = 24 | |
245 | /// [src/main.rs:11] factorial(4) = 24 | |
246 | /// ``` | |
247 | /// | |
248 | /// The `dbg!(..)` macro moves the input: | |
249 | /// | |
250 | /// ```compile_fail | |
0bf4aa26 XL |
251 | /// /// A wrapper around `usize` which importantly is not Copyable. |
252 | /// #[derive(Debug)] | |
253 | /// struct NoCopy(usize); | |
254 | /// | |
255 | /// let a = NoCopy(42); | |
256 | /// let _ = dbg!(a); // <-- `a` is moved here. | |
257 | /// let _ = dbg!(a); // <-- `a` is moved again; error! | |
258 | /// ``` | |
259 | /// | |
532ac7d7 XL |
260 | /// You can also use `dbg!()` without a value to just print the |
261 | /// file and line whenever it's reached. | |
262 | /// | |
48663c56 XL |
263 | /// Finally, if you want to `dbg!(..)` multiple values, it will treat them as |
264 | /// a tuple (and return it, too): | |
265 | /// | |
266 | /// ``` | |
267 | /// assert_eq!(dbg!(1usize, 2u32), (1, 2)); | |
268 | /// ``` | |
269 | /// | |
270 | /// However, a single argument with a trailing comma will still not be treated | |
271 | /// as a tuple, following the convention of ignoring trailing commas in macro | |
272 | /// invocations. You can use a 1-tuple directly if you need one: | |
273 | /// | |
274 | /// ``` | |
275 | /// assert_eq!(1, dbg!(1u32,)); // trailing comma ignored | |
276 | /// assert_eq!((1,), dbg!((1u32,))); // 1-tuple | |
277 | /// ``` | |
278 | /// | |
0bf4aa26 | 279 | /// [stderr]: https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr) |
532ac7d7 XL |
280 | /// [`debug!`]: https://docs.rs/log/*/log/macro.debug.html |
281 | /// [`log`]: https://crates.io/crates/log | |
0bf4aa26 | 282 | #[macro_export] |
a1dfa0c6 | 283 | #[stable(feature = "dbg_macro", since = "1.32.0")] |
0bf4aa26 | 284 | macro_rules! dbg { |
532ac7d7 | 285 | () => { |
e1599b0c | 286 | $crate::eprintln!("[{}:{}]", $crate::file!(), $crate::line!()); |
532ac7d7 | 287 | }; |
29967ef6 | 288 | ($val:expr $(,)?) => { |
0bf4aa26 XL |
289 | // Use of `match` here is intentional because it affects the lifetimes |
290 | // of temporaries - https://stackoverflow.com/a/48732525/1063961 | |
291 | match $val { | |
292 | tmp => { | |
48663c56 | 293 | $crate::eprintln!("[{}:{}] {} = {:#?}", |
e1599b0c | 294 | $crate::file!(), $crate::line!(), $crate::stringify!($val), &tmp); |
0bf4aa26 XL |
295 | tmp |
296 | } | |
297 | } | |
48663c56 | 298 | }; |
48663c56 XL |
299 | ($($val:expr),+ $(,)?) => { |
300 | ($($crate::dbg!($val)),+,) | |
301 | }; | |
1a4d82fc JJ |
302 | } |
303 | ||
e9174d1e SL |
304 | #[cfg(test)] |
305 | macro_rules! assert_approx_eq { | |
60c5eb7d | 306 | ($a:expr, $b:expr) => {{ |
e9174d1e | 307 | let (a, b) = (&$a, &$b); |
60c5eb7d XL |
308 | assert!((*a - *b).abs() < 1.0e-6, "{} is not approximately equal to {}", *a, *b); |
309 | }}; | |
e9174d1e | 310 | } |