@@ -220,6 +220,126 @@ macro_rules! eprintln {
220220 } )
221221}
222222
223+ /// A macro for quick and dirty debugging with which you can inspect
224+ /// the value of a given expression. An example:
225+ ///
226+ /// ```rust
227+ /// #![feature(dbg_macro)]
228+ ///
229+ /// let a = 2;
230+ /// let b = dbg!(a * 2) + 1;
231+ /// // ^-- prints: [src/main.rs:4] a * 2 = 4
232+ /// assert_eq!(b, 5);
233+ /// ```
234+ ///
235+ /// The macro works by using the `Debug` implementation of the type of
236+ /// the given expression to print the value to [stderr] along with the
237+ /// source location of the macro invocation as well as the source code
238+ /// of the expression.
239+ ///
240+ /// Invoking the macro on an expression moves and takes ownership of it
241+ /// before returning the evaluated expression unchanged. If the type
242+ /// of the expression does not implement `Copy` and you don't want
243+ /// to give up ownership, you can instead borrow with `dbg!(&expr)`
244+ /// for some expression `expr`.
245+ ///
246+ /// Note that the macro is intended as a debugging tool and therefore you
247+ /// should avoid having uses of it in version control for longer periods.
248+ /// Use cases involving debug output that should be added to version control
249+ /// may be better served by macros such as `debug!` from the `log` crate.
250+ ///
251+ /// # Stability
252+ ///
253+ /// The exact output printed by this macro should not be relied upon
254+ /// and is subject to future changes.
255+ ///
256+ /// # Panics
257+ ///
258+ /// Panics if writing to `io::stderr` fails.
259+ ///
260+ /// # Further examples
261+ ///
262+ /// With a method call:
263+ ///
264+ /// ```rust
265+ /// #![feature(dbg_macro)]
266+ ///
267+ /// fn foo(n: usize) {
268+ /// if let Some(_) = dbg!(n.checked_sub(4)) {
269+ /// // ...
270+ /// }
271+ /// }
272+ ///
273+ /// foo(3)
274+ /// ```
275+ ///
276+ /// This prints to [stderr]:
277+ ///
278+ /// ```text,ignore
279+ /// [src/main.rs:4] n.checked_sub(4) = None
280+ /// ```
281+ ///
282+ /// Naive factorial implementation:
283+ ///
284+ /// ```rust
285+ /// #![feature(dbg_macro)]
286+ ///
287+ /// fn factorial(n: u32) -> u32 {
288+ /// if dbg!(n <= 1) {
289+ /// dbg!(1)
290+ /// } else {
291+ /// dbg!(n * factorial(n - 1))
292+ /// }
293+ /// }
294+ ///
295+ /// dbg!(factorial(4));
296+ /// ```
297+ ///
298+ /// This prints to [stderr]:
299+ ///
300+ /// ```text,ignore
301+ /// [src/main.rs:3] n <= 1 = false
302+ /// [src/main.rs:3] n <= 1 = false
303+ /// [src/main.rs:3] n <= 1 = false
304+ /// [src/main.rs:3] n <= 1 = true
305+ /// [src/main.rs:4] 1 = 1
306+ /// [src/main.rs:5] n * factorial(n - 1) = 2
307+ /// [src/main.rs:5] n * factorial(n - 1) = 6
308+ /// [src/main.rs:5] n * factorial(n - 1) = 24
309+ /// [src/main.rs:11] factorial(4) = 24
310+ /// ```
311+ ///
312+ /// The `dbg!(..)` macro moves the input:
313+ ///
314+ /// ```compile_fail
315+ /// #![feature(dbg_macro)]
316+ ///
317+ /// /// A wrapper around `usize` which importantly is not Copyable.
318+ /// #[derive(Debug)]
319+ /// struct NoCopy(usize);
320+ ///
321+ /// let a = NoCopy(42);
322+ /// let _ = dbg!(a); // <-- `a` is moved here.
323+ /// let _ = dbg!(a); // <-- `a` is moved again; error!
324+ /// ```
325+ ///
326+ /// [stderr]: https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)
327+ #[ macro_export]
328+ #[ unstable( feature = "dbg_macro" , issue = "54306" ) ]
329+ macro_rules! dbg {
330+ ( $val: expr) => {
331+ // Use of `match` here is intentional because it affects the lifetimes
332+ // of temporaries - https://stackoverflow.com/a/48732525/1063961
333+ match $val {
334+ tmp => {
335+ eprintln!( "[{}:{}] {} = {:#?}" ,
336+ file!( ) , line!( ) , stringify!( $val) , & tmp) ;
337+ tmp
338+ }
339+ }
340+ }
341+ }
342+
223343#[ macro_export]
224344#[ unstable( feature = "await_macro" , issue = "50547" ) ]
225345#[ allow_internal_unstable]
0 commit comments