std/macros.rs
1//! Standard library macros
2//!
3//! This module contains a set of macros which are exported from the standard
4//! library. Each macro is available for use when linking against the standard
5//! library.
6// ignore-tidy-dbg
7
8#[cfg(test)]
9mod tests;
10
11#[doc = include_str!("../../core/src/macros/panic.md")]
12#[macro_export]
13#[rustc_builtin_macro(std_panic)]
14#[stable(feature = "rust1", since = "1.0.0")]
15#[allow_internal_unstable(edition_panic)]
16#[cfg_attr(not(test), rustc_diagnostic_item = "std_panic_macro")]
17macro_rules! panic {
18 // Expands to either `$crate::panic::panic_2015` or `$crate::panic::panic_2021`
19 // depending on the edition of the caller.
20 ($($arg:tt)*) => {
21 /* compiler built-in */
22 };
23}
24
25/// Prints to the standard output.
26///
27/// Equivalent to the [`println!`] macro except that a newline is not printed at
28/// the end of the message.
29///
30/// Note that stdout is frequently line-buffered by default so it may be
31/// necessary to use [`io::stdout().flush()`][flush] to ensure the output is emitted
32/// immediately.
33///
34/// The `print!` macro will lock the standard output on each call. If you call
35/// `print!` within a hot loop, this behavior may be the bottleneck of the loop.
36/// To avoid this, lock stdout with [`io::stdout().lock()`][lock]:
37/// ```
38/// use std::io::{stdout, Write};
39///
40/// let mut lock = stdout().lock();
41/// write!(lock, "hello world").unwrap();
42/// ```
43///
44/// Use `print!` only for the primary output of your program. Use
45/// [`eprint!`] instead to print error and progress messages.
46///
47/// See the formatting documentation in [`std::fmt`](crate::fmt)
48/// for details of the macro argument syntax.
49///
50/// [flush]: crate::io::Write::flush
51/// [`println!`]: crate::println
52/// [`eprint!`]: crate::eprint
53/// [lock]: crate::io::Stdout
54///
55/// # Panics
56///
57/// Panics if writing to `io::stdout()` fails.
58///
59/// Writing to non-blocking stdout can cause an error, which will lead
60/// this macro to panic.
61///
62/// # Examples
63///
64/// ```
65/// use std::io::{self, Write};
66///
67/// print!("this ");
68/// print!("will ");
69/// print!("be ");
70/// print!("on ");
71/// print!("the ");
72/// print!("same ");
73/// print!("line ");
74///
75/// io::stdout().flush().unwrap();
76///
77/// print!("this string has a newline, why not choose println! instead?\n");
78///
79/// io::stdout().flush().unwrap();
80/// ```
81#[macro_export]
82#[stable(feature = "rust1", since = "1.0.0")]
83#[cfg_attr(not(test), rustc_diagnostic_item = "print_macro")]
84#[allow_internal_unstable(print_internals)]
85macro_rules! print {
86 ($($arg:tt)*) => {{
87 $crate::io::_print($crate::format_args!($($arg)*));
88 }};
89}
90
91/// Prints to the standard output, with a newline.
92///
93/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
94/// (no additional CARRIAGE RETURN (`\r`/`U+000D`)).
95///
96/// This macro uses the same syntax as [`format!`], but writes to the standard output instead.
97/// See [`std::fmt`] for more information.
98///
99/// The `println!` macro will lock the standard output on each call. If you call
100/// `println!` within a hot loop, this behavior may be the bottleneck of the loop.
101/// To avoid this, lock stdout with [`io::stdout().lock()`][lock]:
102/// ```
103/// use std::io::{stdout, Write};
104///
105/// let mut lock = stdout().lock();
106/// writeln!(lock, "hello world").unwrap();
107/// ```
108///
109/// Use `println!` only for the primary output of your program. Use
110/// [`eprintln!`] instead to print error and progress messages.
111///
112/// See the formatting documentation in [`std::fmt`](crate::fmt)
113/// for details of the macro argument syntax.
114///
115/// [`std::fmt`]: crate::fmt
116/// [`eprintln!`]: crate::eprintln
117/// [lock]: crate::io::Stdout
118///
119/// # Panics
120///
121/// Panics if writing to [`io::stdout`] fails.
122///
123/// Writing to non-blocking stdout can cause an error, which will lead
124/// this macro to panic.
125///
126/// [`io::stdout`]: crate::io::stdout
127///
128/// # Examples
129///
130/// ```
131/// println!(); // prints just a newline
132/// println!("hello there!");
133/// println!("format {} arguments", "some");
134/// let local_variable = "some";
135/// println!("format {local_variable} arguments");
136/// ```
137#[macro_export]
138#[stable(feature = "rust1", since = "1.0.0")]
139#[cfg_attr(not(test), rustc_diagnostic_item = "println_macro")]
140#[allow_internal_unstable(print_internals, format_args_nl)]
141macro_rules! println {
142 () => {
143 $crate::print!("\n")
144 };
145 ($($arg:tt)*) => {{
146 $crate::io::_print($crate::format_args_nl!($($arg)*));
147 }};
148}
149
150/// Prints to the standard error.
151///
152/// Equivalent to the [`print!`] macro, except that output goes to
153/// [`io::stderr`] instead of [`io::stdout`]. See [`print!`] for
154/// example usage.
155///
156/// Use `eprint!` only for error and progress messages. Use `print!`
157/// instead for the primary output of your program.
158///
159/// [`io::stderr`]: crate::io::stderr
160/// [`io::stdout`]: crate::io::stdout
161///
162/// See the formatting documentation in [`std::fmt`](crate::fmt)
163/// for details of the macro argument syntax.
164///
165/// # Panics
166///
167/// Panics if writing to `io::stderr` fails.
168///
169/// Writing to non-blocking stderr can cause an error, which will lead
170/// this macro to panic.
171///
172/// # Examples
173///
174/// ```
175/// eprint!("Error: Could not complete task");
176/// ```
177#[macro_export]
178#[stable(feature = "eprint", since = "1.19.0")]
179#[cfg_attr(not(test), rustc_diagnostic_item = "eprint_macro")]
180#[allow_internal_unstable(print_internals)]
181macro_rules! eprint {
182 ($($arg:tt)*) => {{
183 $crate::io::_eprint($crate::format_args!($($arg)*));
184 }};
185}
186
187/// Prints to the standard error, with a newline.
188///
189/// Equivalent to the [`println!`] macro, except that output goes to
190/// [`io::stderr`] instead of [`io::stdout`]. See [`println!`] for
191/// example usage.
192///
193/// Use `eprintln!` only for error and progress messages. Use `println!`
194/// instead for the primary output of your program.
195///
196/// See the formatting documentation in [`std::fmt`](crate::fmt)
197/// for details of the macro argument syntax.
198///
199/// [`io::stderr`]: crate::io::stderr
200/// [`io::stdout`]: crate::io::stdout
201/// [`println!`]: crate::println
202///
203/// # Panics
204///
205/// Panics if writing to `io::stderr` fails.
206///
207/// Writing to non-blocking stderr can cause an error, which will lead
208/// this macro to panic.
209///
210/// # Examples
211///
212/// ```
213/// eprintln!("Error: Could not complete task");
214/// ```
215#[macro_export]
216#[stable(feature = "eprint", since = "1.19.0")]
217#[cfg_attr(not(test), rustc_diagnostic_item = "eprintln_macro")]
218#[allow_internal_unstable(print_internals, format_args_nl)]
219macro_rules! eprintln {
220 () => {
221 $crate::eprint!("\n")
222 };
223 ($($arg:tt)*) => {{
224 $crate::io::_eprint($crate::format_args_nl!($($arg)*));
225 }};
226}
227
228/// Prints and returns the value of a given expression for quick and dirty
229/// debugging.
230///
231/// An example:
232///
233/// ```rust
234/// let a = 2;
235/// let b = dbg!(a * 2) + 1;
236/// // ^-- prints: [src/main.rs:2:9] a * 2 = 4
237/// assert_eq!(b, 5);
238/// ```
239///
240/// The macro works by using the `Debug` implementation of the type of
241/// the given expression to print the value to [stderr] along with the
242/// source location of the macro invocation as well as the source code
243/// of the expression.
244///
245/// Invoking the macro on an expression moves and takes ownership of it
246/// before returning the evaluated expression unchanged. If the type
247/// of the expression does not implement `Copy` and you don't want
248/// to give up ownership, you can instead borrow with `dbg!(&expr)`
249/// for some expression `expr`.
250///
251/// The `dbg!` macro works exactly the same in release builds.
252/// This is useful when debugging issues that only occur in release
253/// builds or when debugging in release mode is significantly faster.
254///
255/// Note that the macro is intended as a debugging tool and therefore you
256/// should avoid having uses of it in version control for long periods
257/// (other than in tests and similar).
258/// Debug output from production code is better done with other facilities
259/// such as the [`debug!`] macro from the [`log`] crate.
260///
261/// # Stability
262///
263/// The exact output printed by this macro should not be relied upon
264/// and is subject to future changes.
265///
266/// # Panics
267///
268/// Panics if writing to `io::stderr` fails.
269///
270/// # Further examples
271///
272/// With a method call:
273///
274/// ```rust
275/// fn foo(n: usize) {
276/// if let Some(_) = dbg!(n.checked_sub(4)) {
277/// // ...
278/// }
279/// }
280///
281/// foo(3)
282/// ```
283///
284/// This prints to [stderr]:
285///
286/// ```text,ignore
287/// [src/main.rs:2:22] n.checked_sub(4) = None
288/// ```
289///
290/// Naive factorial implementation:
291///
292/// ```rust
293/// fn factorial(n: u32) -> u32 {
294/// if dbg!(n <= 1) {
295/// dbg!(1)
296/// } else {
297/// dbg!(n * factorial(n - 1))
298/// }
299/// }
300///
301/// dbg!(factorial(4));
302/// ```
303///
304/// This prints to [stderr]:
305///
306/// ```text,ignore
307/// [src/main.rs:2:8] n <= 1 = false
308/// [src/main.rs:2:8] n <= 1 = false
309/// [src/main.rs:2:8] n <= 1 = false
310/// [src/main.rs:2:8] n <= 1 = true
311/// [src/main.rs:3:9] 1 = 1
312/// [src/main.rs:7:9] n * factorial(n - 1) = 2
313/// [src/main.rs:7:9] n * factorial(n - 1) = 6
314/// [src/main.rs:7:9] n * factorial(n - 1) = 24
315/// [src/main.rs:9:1] factorial(4) = 24
316/// ```
317///
318/// The `dbg!(..)` macro moves the input:
319///
320/// ```compile_fail
321/// /// A wrapper around `usize` which importantly is not Copyable.
322/// #[derive(Debug)]
323/// struct NoCopy(usize);
324///
325/// let a = NoCopy(42);
326/// let _ = dbg!(a); // <-- `a` is moved here.
327/// let _ = dbg!(a); // <-- `a` is moved again; error!
328/// ```
329///
330/// You can also use `dbg!()` without a value to just print the
331/// file and line whenever it's reached.
332///
333/// Finally, if you want to `dbg!(..)` multiple values, it will treat them as
334/// a tuple (and return it, too):
335///
336/// ```
337/// assert_eq!(dbg!(1usize, 2u32), (1, 2));
338/// ```
339///
340/// However, a single argument with a trailing comma will still not be treated
341/// as a tuple, following the convention of ignoring trailing commas in macro
342/// invocations. You can use a 1-tuple directly if you need one:
343///
344/// ```
345/// assert_eq!(1, dbg!(1u32,)); // trailing comma ignored
346/// assert_eq!((1,), dbg!((1u32,))); // 1-tuple
347/// ```
348///
349/// [stderr]: https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)
350/// [`debug!`]: https://docs.rs/log/*/log/macro.debug.html
351/// [`log`]: https://crates.io/crates/log
352#[macro_export]
353#[allow_internal_unstable(std_internals)]
354#[cfg_attr(not(test), rustc_diagnostic_item = "dbg_macro")]
355#[stable(feature = "dbg_macro", since = "1.32.0")]
356macro_rules! dbg {
357 () => {
358 $crate::eprintln!("[{}:{}:{}]", $crate::file!(), $crate::line!(), $crate::column!())
359 };
360 ($($val:expr),+ $(,)?) => {
361 $crate::macros::dbg_internal!(() () ($($val),+))
362 };
363}
364
365/// Internal macro that processes a list of expressions, binds their results
366/// with `match`, calls `eprint!` with the collected information, and returns
367/// all the evaluated expressions in a tuple.
368///
369/// E.g. `dbg_internal!(() () (1, 2))` expands into
370/// ```rust, ignore
371/// match (1, 2) {
372/// (tmp_1, tmp_2) => {
373/// eprint!("...", &tmp_1, &tmp_2, /* some other arguments */);
374/// (tmp_1, tmp_2)
375/// }
376/// }
377/// ```
378///
379/// This is necessary so that `dbg!` outputs don't get torn, see #136703.
380#[doc(hidden)]
381#[rustc_macro_transparency = "semiopaque"]
382pub macro dbg_internal {
383 (($($piece:literal),+) ($($processed:expr => $bound:ident),+) ()) => {
384 // Use of `match` here is intentional because it affects the lifetimes
385 // of temporaries - https://stackoverflow.com/a/48732525/1063961
386 // Always put the arguments in a tuple to avoid an unused parens lint on the pattern.
387 match ($($processed,)+) {
388 ($($bound,)+) => {
389 $crate::eprint!(
390 $crate::concat!($($piece),+),
391 $(
392 $crate::stringify!($processed),
393 // The `&T: Debug` check happens here (not in the format literal desugaring)
394 // to avoid format literal related messages and suggestions.
395 &&$bound as &dyn $crate::fmt::Debug
396 ),+,
397 // The location returned here is that of the macro invocation, so
398 // it will be the same for all expressions. Thus, label these
399 // arguments so that they can be reused in every piece of the
400 // formatting template.
401 file=$crate::file!(),
402 line=$crate::line!(),
403 column=$crate::column!()
404 );
405 // Comma separate the variables only when necessary so that this will
406 // not yield a tuple for a single expression, but rather just parenthesize
407 // the expression.
408 ($($bound),+)
409
410 }
411 }
412 },
413 (($($piece:literal),*) ($($processed:expr => $bound:ident),*) ($val:expr $(,$rest:expr)*)) => {
414 $crate::macros::dbg_internal!(
415 ($($piece,)* "[{file}:{line}:{column}] {} = {:#?}\n")
416 ($($processed => $bound,)* $val => tmp)
417 ($($rest),*)
418 )
419 },
420}
421
422#[doc(hidden)]
423#[macro_export]
424#[allow_internal_unstable(hash_map_internals)]
425#[unstable(feature = "hash_map_internals", issue = "none")]
426macro_rules! repetition_utils {
427 (@count $($tokens:tt),*) => {{
428 [$($crate::repetition_utils!(@replace $tokens => ())),*].len()
429 }};
430
431 (@replace $x:tt => $y:tt) => { $y }
432}
433
434/// Creates a [`HashMap`] containing the arguments.
435///
436/// `hash_map!` allows specifying the entries that make
437/// up the [`HashMap`] where the key and value are separated by a `=>`.
438///
439/// The entries are separated by commas with a trailing comma being allowed.
440///
441/// It is semantically equivalent to using repeated [`HashMap::insert`]
442/// on a newly created hashmap.
443///
444/// `hash_map!` will attempt to avoid repeated reallocations by
445/// using [`HashMap::with_capacity`].
446///
447/// # Examples
448///
449/// ```rust
450/// #![feature(hash_map_macro)]
451/// use std::hash_map;
452///
453/// let map = hash_map! {
454/// "key" => "value",
455/// "key1" => "value1"
456/// };
457///
458/// assert_eq!(map.get("key"), Some(&"value"));
459/// assert_eq!(map.get("key1"), Some(&"value1"));
460/// assert!(map.get("brrrrrrooooommm").is_none());
461/// ```
462///
463/// And with a trailing comma
464///
465///```rust
466/// #![feature(hash_map_macro)]
467/// use std::hash_map;
468///
469/// let map = hash_map! {
470/// "key" => "value", // notice the ,
471/// };
472///
473/// assert_eq!(map.get("key"), Some(&"value"));
474/// ```
475///
476/// The key and value are moved into the HashMap.
477///
478/// [`HashMap`]: crate::collections::HashMap
479/// [`HashMap::insert`]: crate::collections::HashMap::insert
480/// [`HashMap::with_capacity`]: crate::collections::HashMap::with_capacity
481#[macro_export]
482#[allow_internal_unstable(hash_map_internals)]
483#[unstable(feature = "hash_map_macro", issue = "144032")]
484macro_rules! hash_map {
485 () => {{
486 $crate::collections::HashMap::new()
487 }};
488
489 ( $( $key:expr => $value:expr ),* $(,)? ) => {{
490 let mut map = $crate::collections::HashMap::with_capacity(
491 const { $crate::repetition_utils!(@count $($key),*) }
492 );
493 $( map.insert($key, $value); )*
494 map
495 }}
496}