1#[doc = include_str!("panic.md")]
2#[macro_export]
3#[rustc_builtin_macro(core_panic)]
4#[allow_internal_unstable(edition_panic)]
5#[stable(feature = "core", since = "1.6.0")]
6#[rustc_diagnostic_item = "core_panic_macro"]
7macro_rules! panic {
8 // Expands to either `$crate::panic::panic_2015` or `$crate::panic::panic_2021`
9 // depending on the edition of the caller.
10 ($($arg:tt)*) => {
11 /* compiler built-in */
12 };
13}
14
15/// Asserts that two expressions are equal to each other (using [`PartialEq`]).
16///
17/// Assertions are always checked in both debug and release builds, and cannot
18/// be disabled. See [`debug_assert_eq!`] for assertions that are disabled in
19/// release builds by default.
20///
21/// [`debug_assert_eq!`]: crate::debug_assert_eq
22///
23/// On panic, this macro will print the values of the expressions with their
24/// debug representations.
25///
26/// Like [`assert!`], this macro has a second form, where a custom
27/// panic message can be provided.
28///
29/// # Examples
30///
31/// ```
32/// let a = 3;
33/// let b = 1 + 2;
34/// assert_eq!(a, b);
35///
36/// assert_eq!(a, b, "we are testing addition with {} and {}", a, b);
37/// ```
38#[macro_export]
39#[stable(feature = "rust1", since = "1.0.0")]
40#[rustc_diagnostic_item = "assert_eq_macro"]
41#[allow_internal_unstable(panic_internals)]
42macro_rules! assert_eq {
43 ($left:expr, $right:expr $(,)?) => {
44 match (&$left, &$right) {
45 (left_val, right_val) => {
46 if !(*left_val == *right_val) {
47 let kind = $crate::panicking::AssertKind::Eq;
48 // The reborrows below are intentional. Without them, the stack slot for the
49 // borrow is initialized even before the values are compared, leading to a
50 // noticeable slow down.
51 $crate::panicking::assert_failed(kind, &*left_val, &*right_val, $crate::option::Option::None);
52 }
53 }
54 }
55 };
56 ($left:expr, $right:expr, $($arg:tt)+) => {
57 match (&$left, &$right) {
58 (left_val, right_val) => {
59 if !(*left_val == *right_val) {
60 let kind = $crate::panicking::AssertKind::Eq;
61 // The reborrows below are intentional. Without them, the stack slot for the
62 // borrow is initialized even before the values are compared, leading to a
63 // noticeable slow down.
64 $crate::panicking::assert_failed(kind, &*left_val, &*right_val, $crate::option::Option::Some($crate::format_args!($($arg)+)));
65 }
66 }
67 }
68 };
69}
70
71/// Asserts that two expressions are not equal to each other (using [`PartialEq`]).
72///
73/// Assertions are always checked in both debug and release builds, and cannot
74/// be disabled. See [`debug_assert_ne!`] for assertions that are disabled in
75/// release builds by default.
76///
77/// [`debug_assert_ne!`]: crate::debug_assert_ne
78///
79/// On panic, this macro will print the values of the expressions with their
80/// debug representations.
81///
82/// Like [`assert!`], this macro has a second form, where a custom
83/// panic message can be provided.
84///
85/// # Examples
86///
87/// ```
88/// let a = 3;
89/// let b = 2;
90/// assert_ne!(a, b);
91///
92/// assert_ne!(a, b, "we are testing that the values are not equal");
93/// ```
94#[macro_export]
95#[stable(feature = "assert_ne", since = "1.13.0")]
96#[rustc_diagnostic_item = "assert_ne_macro"]
97#[allow_internal_unstable(panic_internals)]
98macro_rules! assert_ne {
99 ($left:expr, $right:expr $(,)?) => {
100 match (&$left, &$right) {
101 (left_val, right_val) => {
102 if *left_val == *right_val {
103 let kind = $crate::panicking::AssertKind::Ne;
104 // The reborrows below are intentional. Without them, the stack slot for the
105 // borrow is initialized even before the values are compared, leading to a
106 // noticeable slow down.
107 $crate::panicking::assert_failed(kind, &*left_val, &*right_val, $crate::option::Option::None);
108 }
109 }
110 }
111 };
112 ($left:expr, $right:expr, $($arg:tt)+) => {
113 match (&($left), &($right)) {
114 (left_val, right_val) => {
115 if *left_val == *right_val {
116 let kind = $crate::panicking::AssertKind::Ne;
117 // The reborrows below are intentional. Without them, the stack slot for the
118 // borrow is initialized even before the values are compared, leading to a
119 // noticeable slow down.
120 $crate::panicking::assert_failed(kind, &*left_val, &*right_val, $crate::option::Option::Some($crate::format_args!($($arg)+)));
121 }
122 }
123 }
124 };
125}
126
127/// Asserts that an expression matches the provided pattern.
128///
129/// This macro is generally preferable to `assert!(matches!(value, pattern))`, because it can print
130/// the debug representation of the actual value shape that did not meet expectations. In contrast,
131/// using [`assert!`] will only print that expectations were not met, but not why.
132///
133/// The pattern syntax is exactly the same as found in a match arm and the `matches!` macro. The
134/// optional if guard can be used to add additional checks that must be true for the matched value,
135/// otherwise this macro will panic.
136///
137/// Assertions are always checked in both debug and release builds, and cannot
138/// be disabled. See [`debug_assert_matches!`] for assertions that are disabled in
139/// release builds by default.
140///
141/// [`debug_assert_matches!`]: crate::assert_matches::debug_assert_matches
142///
143/// On panic, this macro will print the value of the expression with its debug representation.
144///
145/// Like [`assert!`], this macro has a second form, where a custom panic message can be provided.
146///
147/// # Examples
148///
149/// ```
150/// #![feature(assert_matches)]
151///
152/// use std::assert_matches::assert_matches;
153///
154/// let a = Some(345);
155/// let b = Some(56);
156/// assert_matches!(a, Some(_));
157/// assert_matches!(b, Some(_));
158///
159/// assert_matches!(a, Some(345));
160/// assert_matches!(a, Some(345) | None);
161///
162/// // assert_matches!(a, None); // panics
163/// // assert_matches!(b, Some(345)); // panics
164/// // assert_matches!(b, Some(345) | None); // panics
165///
166/// assert_matches!(a, Some(x) if x > 100);
167/// // assert_matches!(a, Some(x) if x < 100); // panics
168/// ```
169#[unstable(feature = "assert_matches", issue = "82775")]
170#[allow_internal_unstable(panic_internals)]
171#[rustc_macro_transparency = "semitransparent"]
172pub macro assert_matches {
173 ($left:expr, $(|)? $( $pattern:pat_param )|+ $( if $guard: expr )? $(,)?) => {
174 match $left {
175 $( $pattern )|+ $( if $guard )? => {}
176 ref left_val => {
177 $crate::panicking::assert_matches_failed(
178 left_val,
179 $crate::stringify!($($pattern)|+ $(if $guard)?),
180 $crate::option::Option::None
181 );
182 }
183 }
184 },
185 ($left:expr, $(|)? $( $pattern:pat_param )|+ $( if $guard: expr )?, $($arg:tt)+) => {
186 match $left {
187 $( $pattern )|+ $( if $guard )? => {}
188 ref left_val => {
189 $crate::panicking::assert_matches_failed(
190 left_val,
191 $crate::stringify!($($pattern)|+ $(if $guard)?),
192 $crate::option::Option::Some($crate::format_args!($($arg)+))
193 );
194 }
195 }
196 },
197}
198
199/// A macro for defining `#[cfg]` match-like statements.
200///
201/// It is similar to the `if/elif` C preprocessor macro by allowing definition of a cascade of
202/// `#[cfg]` cases, emitting the implementation which matches first.
203///
204/// This allows you to conveniently provide a long list `#[cfg]`'d blocks of code
205/// without having to rewrite each clause multiple times.
206///
207/// Trailing `_` wildcard match arms are **optional** and they indicate a fallback branch when
208/// all previous declarations do not evaluate to true.
209///
210/// # Example
211///
212/// ```
213/// #![feature(cfg_select)]
214///
215/// cfg_select! {
216/// unix => {
217/// fn foo() { /* unix specific functionality */ }
218/// }
219/// target_pointer_width = "32" => {
220/// fn foo() { /* non-unix, 32-bit functionality */ }
221/// }
222/// _ => {
223/// fn foo() { /* fallback implementation */ }
224/// }
225/// }
226/// ```
227///
228/// If desired, it is possible to return expressions through the use of surrounding braces:
229///
230/// ```
231/// #![feature(cfg_select)]
232///
233/// let _some_string = cfg_select! {{
234/// unix => { "With great power comes great electricity bills" }
235/// _ => { "Behind every successful diet is an unwatched pizza" }
236/// }};
237/// ```
238#[unstable(feature = "cfg_select", issue = "115585")]
239#[rustc_diagnostic_item = "cfg_select"]
240#[rustc_macro_transparency = "semitransparent"]
241pub macro cfg_select {
242 ({ $($tt:tt)* }) => {{
243 $crate::cfg_select! { $($tt)* }
244 }},
245 (_ => { $($output:tt)* }) => {
246 $($output)*
247 },
248 (
249 $cfg:meta => $output:tt
250 $($( $rest:tt )+)?
251 ) => {
252 #[cfg($cfg)]
253 $crate::cfg_select! { _ => $output }
254 $(
255 #[cfg(not($cfg))]
256 $crate::cfg_select! { $($rest)+ }
257 )?
258 },
259}
260
261/// Asserts that a boolean expression is `true` at runtime.
262///
263/// This will invoke the [`panic!`] macro if the provided expression cannot be
264/// evaluated to `true` at runtime.
265///
266/// Like [`assert!`], this macro also has a second version, where a custom panic
267/// message can be provided.
268///
269/// # Uses
270///
271/// Unlike [`assert!`], `debug_assert!` statements are only enabled in non
272/// optimized builds by default. An optimized build will not execute
273/// `debug_assert!` statements unless `-C debug-assertions` is passed to the
274/// compiler. This makes `debug_assert!` useful for checks that are too
275/// expensive to be present in a release build but may be helpful during
276/// development. The result of expanding `debug_assert!` is always type checked.
277///
278/// An unchecked assertion allows a program in an inconsistent state to keep
279/// running, which might have unexpected consequences but does not introduce
280/// unsafety as long as this only happens in safe code. The performance cost
281/// of assertions, however, is not measurable in general. Replacing [`assert!`]
282/// with `debug_assert!` is thus only encouraged after thorough profiling, and
283/// more importantly, only in safe code!
284///
285/// # Examples
286///
287/// ```
288/// // the panic message for these assertions is the stringified value of the
289/// // expression given.
290/// debug_assert!(true);
291///
292/// fn some_expensive_computation() -> bool { true } // a very simple function
293/// debug_assert!(some_expensive_computation());
294///
295/// // assert with a custom message
296/// let x = true;
297/// debug_assert!(x, "x wasn't true!");
298///
299/// let a = 3; let b = 27;
300/// debug_assert!(a + b == 30, "a = {}, b = {}", a, b);
301/// ```
302#[macro_export]
303#[stable(feature = "rust1", since = "1.0.0")]
304#[rustc_diagnostic_item = "debug_assert_macro"]
305#[allow_internal_unstable(edition_panic)]
306macro_rules! debug_assert {
307 ($($arg:tt)*) => {
308 if $crate::cfg!(debug_assertions) {
309 $crate::assert!($($arg)*);
310 }
311 };
312}
313
314/// Asserts that two expressions are equal to each other.
315///
316/// On panic, this macro will print the values of the expressions with their
317/// debug representations.
318///
319/// Unlike [`assert_eq!`], `debug_assert_eq!` statements are only enabled in non
320/// optimized builds by default. An optimized build will not execute
321/// `debug_assert_eq!` statements unless `-C debug-assertions` is passed to the
322/// compiler. This makes `debug_assert_eq!` useful for checks that are too
323/// expensive to be present in a release build but may be helpful during
324/// development. The result of expanding `debug_assert_eq!` is always type checked.
325///
326/// # Examples
327///
328/// ```
329/// let a = 3;
330/// let b = 1 + 2;
331/// debug_assert_eq!(a, b);
332/// ```
333#[macro_export]
334#[stable(feature = "rust1", since = "1.0.0")]
335#[rustc_diagnostic_item = "debug_assert_eq_macro"]
336macro_rules! debug_assert_eq {
337 ($($arg:tt)*) => {
338 if $crate::cfg!(debug_assertions) {
339 $crate::assert_eq!($($arg)*);
340 }
341 };
342}
343
344/// Asserts that two expressions are not equal to each other.
345///
346/// On panic, this macro will print the values of the expressions with their
347/// debug representations.
348///
349/// Unlike [`assert_ne!`], `debug_assert_ne!` statements are only enabled in non
350/// optimized builds by default. An optimized build will not execute
351/// `debug_assert_ne!` statements unless `-C debug-assertions` is passed to the
352/// compiler. This makes `debug_assert_ne!` useful for checks that are too
353/// expensive to be present in a release build but may be helpful during
354/// development. The result of expanding `debug_assert_ne!` is always type checked.
355///
356/// # Examples
357///
358/// ```
359/// let a = 3;
360/// let b = 2;
361/// debug_assert_ne!(a, b);
362/// ```
363#[macro_export]
364#[stable(feature = "assert_ne", since = "1.13.0")]
365#[rustc_diagnostic_item = "debug_assert_ne_macro"]
366macro_rules! debug_assert_ne {
367 ($($arg:tt)*) => {
368 if $crate::cfg!(debug_assertions) {
369 $crate::assert_ne!($($arg)*);
370 }
371 };
372}
373
374/// Asserts that an expression matches the provided pattern.
375///
376/// This macro is generally preferable to `debug_assert!(matches!(value, pattern))`, because it can
377/// print the debug representation of the actual value shape that did not meet expectations. In
378/// contrast, using [`debug_assert!`] will only print that expectations were not met, but not why.
379///
380/// The pattern syntax is exactly the same as found in a match arm and the `matches!` macro. The
381/// optional if guard can be used to add additional checks that must be true for the matched value,
382/// otherwise this macro will panic.
383///
384/// On panic, this macro will print the value of the expression with its debug representation.
385///
386/// Like [`assert!`], this macro has a second form, where a custom panic message can be provided.
387///
388/// Unlike [`assert_matches!`], `debug_assert_matches!` statements are only enabled in non optimized
389/// builds by default. An optimized build will not execute `debug_assert_matches!` statements unless
390/// `-C debug-assertions` is passed to the compiler. This makes `debug_assert_matches!` useful for
391/// checks that are too expensive to be present in a release build but may be helpful during
392/// development. The result of expanding `debug_assert_matches!` is always type checked.
393///
394/// # Examples
395///
396/// ```
397/// #![feature(assert_matches)]
398///
399/// use std::assert_matches::debug_assert_matches;
400///
401/// let a = Some(345);
402/// let b = Some(56);
403/// debug_assert_matches!(a, Some(_));
404/// debug_assert_matches!(b, Some(_));
405///
406/// debug_assert_matches!(a, Some(345));
407/// debug_assert_matches!(a, Some(345) | None);
408///
409/// // debug_assert_matches!(a, None); // panics
410/// // debug_assert_matches!(b, Some(345)); // panics
411/// // debug_assert_matches!(b, Some(345) | None); // panics
412///
413/// debug_assert_matches!(a, Some(x) if x > 100);
414/// // debug_assert_matches!(a, Some(x) if x < 100); // panics
415/// ```
416#[unstable(feature = "assert_matches", issue = "82775")]
417#[allow_internal_unstable(assert_matches)]
418#[rustc_macro_transparency = "semitransparent"]
419pub macro debug_assert_matches($($arg:tt)*) {
420 if $crate::cfg!(debug_assertions) {
421 $crate::assert_matches::assert_matches!($($arg)*);
422 }
423}
424
425/// Returns whether the given expression matches the provided pattern.
426///
427/// The pattern syntax is exactly the same as found in a match arm. The optional if guard can be
428/// used to add additional checks that must be true for the matched value, otherwise this macro will
429/// return `false`.
430///
431/// When testing that a value matches a pattern, it's generally preferable to use
432/// [`assert_matches!`] as it will print the debug representation of the value if the assertion
433/// fails.
434///
435/// # Examples
436///
437/// ```
438/// let foo = 'f';
439/// assert!(matches!(foo, 'A'..='Z' | 'a'..='z'));
440///
441/// let bar = Some(4);
442/// assert!(matches!(bar, Some(x) if x > 2));
443/// ```
444#[macro_export]
445#[stable(feature = "matches_macro", since = "1.42.0")]
446#[rustc_diagnostic_item = "matches_macro"]
447macro_rules! matches {
448 ($expression:expr, $pattern:pat $(if $guard:expr)? $(,)?) => {
449 match $expression {
450 $pattern $(if $guard)? => true,
451 _ => false
452 }
453 };
454}
455
456/// Unwraps a result or propagates its error.
457///
458/// The [`?` operator][propagating-errors] was added to replace `try!`
459/// and should be used instead. Furthermore, `try` is a reserved word
460/// in Rust 2018, so if you must use it, you will need to use the
461/// [raw-identifier syntax][ris]: `r#try`.
462///
463/// [propagating-errors]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator
464/// [ris]: https://doc.rust-lang.org/nightly/rust-by-example/compatibility/raw_identifiers.html
465///
466/// `try!` matches the given [`Result`]. In case of the `Ok` variant, the
467/// expression has the value of the wrapped value.
468///
469/// In case of the `Err` variant, it retrieves the inner error. `try!` then
470/// performs conversion using `From`. This provides automatic conversion
471/// between specialized errors and more general ones. The resulting
472/// error is then immediately returned.
473///
474/// Because of the early return, `try!` can only be used in functions that
475/// return [`Result`].
476///
477/// # Examples
478///
479/// ```
480/// use std::io;
481/// use std::fs::File;
482/// use std::io::prelude::*;
483///
484/// enum MyError {
485/// FileWriteError
486/// }
487///
488/// impl From<io::Error> for MyError {
489/// fn from(e: io::Error) -> MyError {
490/// MyError::FileWriteError
491/// }
492/// }
493///
494/// // The preferred method of quick returning Errors
495/// fn write_to_file_question() -> Result<(), MyError> {
496/// let mut file = File::create("my_best_friends.txt")?;
497/// file.write_all(b"This is a list of my best friends.")?;
498/// Ok(())
499/// }
500///
501/// // The previous method of quick returning Errors
502/// fn write_to_file_using_try() -> Result<(), MyError> {
503/// let mut file = r#try!(File::create("my_best_friends.txt"));
504/// r#try!(file.write_all(b"This is a list of my best friends."));
505/// Ok(())
506/// }
507///
508/// // This is equivalent to:
509/// fn write_to_file_using_match() -> Result<(), MyError> {
510/// let mut file = r#try!(File::create("my_best_friends.txt"));
511/// match file.write_all(b"This is a list of my best friends.") {
512/// Ok(v) => v,
513/// Err(e) => return Err(From::from(e)),
514/// }
515/// Ok(())
516/// }
517/// ```
518#[macro_export]
519#[stable(feature = "rust1", since = "1.0.0")]
520#[deprecated(since = "1.39.0", note = "use the `?` operator instead")]
521#[doc(alias = "?")]
522macro_rules! r#try {
523 ($expr:expr $(,)?) => {
524 match $expr {
525 $crate::result::Result::Ok(val) => val,
526 $crate::result::Result::Err(err) => {
527 return $crate::result::Result::Err($crate::convert::From::from(err));
528 }
529 }
530 };
531}
532
533/// Writes formatted data into a buffer.
534///
535/// This macro accepts a 'writer', a format string, and a list of arguments. Arguments will be
536/// formatted according to the specified format string and the result will be passed to the writer.
537/// The writer may be any value with a `write_fmt` method; generally this comes from an
538/// implementation of either the [`fmt::Write`] or the [`io::Write`] trait. The macro
539/// returns whatever the `write_fmt` method returns; commonly a [`fmt::Result`], or an
540/// [`io::Result`].
541///
542/// See [`std::fmt`] for more information on the format string syntax.
543///
544/// [`std::fmt`]: ../std/fmt/index.html
545/// [`fmt::Write`]: crate::fmt::Write
546/// [`io::Write`]: ../std/io/trait.Write.html
547/// [`fmt::Result`]: crate::fmt::Result
548/// [`io::Result`]: ../std/io/type.Result.html
549///
550/// # Examples
551///
552/// ```
553/// use std::io::Write;
554///
555/// fn main() -> std::io::Result<()> {
556/// let mut w = Vec::new();
557/// write!(&mut w, "test")?;
558/// write!(&mut w, "formatted {}", "arguments")?;
559///
560/// assert_eq!(w, b"testformatted arguments");
561/// Ok(())
562/// }
563/// ```
564///
565/// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
566/// implementing either, as objects do not typically implement both. However, the module must
567/// avoid conflict between the trait names, such as by importing them as `_` or otherwise renaming
568/// them:
569///
570/// ```
571/// use std::fmt::Write as _;
572/// use std::io::Write as _;
573///
574/// fn main() -> Result<(), Box<dyn std::error::Error>> {
575/// let mut s = String::new();
576/// let mut v = Vec::new();
577///
578/// write!(&mut s, "{} {}", "abc", 123)?; // uses fmt::Write::write_fmt
579/// write!(&mut v, "s = {:?}", s)?; // uses io::Write::write_fmt
580/// assert_eq!(v, b"s = \"abc 123\"");
581/// Ok(())
582/// }
583/// ```
584///
585/// If you also need the trait names themselves, such as to implement one or both on your types,
586/// import the containing module and then name them with a prefix:
587///
588/// ```
589/// # #![allow(unused_imports)]
590/// use std::fmt::{self, Write as _};
591/// use std::io::{self, Write as _};
592///
593/// struct Example;
594///
595/// impl fmt::Write for Example {
596/// fn write_str(&mut self, _s: &str) -> core::fmt::Result {
597/// unimplemented!();
598/// }
599/// }
600/// ```
601///
602/// Note: This macro can be used in `no_std` setups as well.
603/// In a `no_std` setup you are responsible for the implementation details of the components.
604///
605/// ```no_run
606/// use core::fmt::Write;
607///
608/// struct Example;
609///
610/// impl Write for Example {
611/// fn write_str(&mut self, _s: &str) -> core::fmt::Result {
612/// unimplemented!();
613/// }
614/// }
615///
616/// let mut m = Example{};
617/// write!(&mut m, "Hello World").expect("Not written");
618/// ```
619#[macro_export]
620#[stable(feature = "rust1", since = "1.0.0")]
621#[rustc_diagnostic_item = "write_macro"]
622macro_rules! write {
623 ($dst:expr, $($arg:tt)*) => {
624 $dst.write_fmt($crate::format_args!($($arg)*))
625 };
626}
627
628/// Writes formatted data into a buffer, with a newline appended.
629///
630/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
631/// (no additional CARRIAGE RETURN (`\r`/`U+000D`).
632///
633/// For more information, see [`write!`]. For information on the format string syntax, see
634/// [`std::fmt`].
635///
636/// [`std::fmt`]: ../std/fmt/index.html
637///
638/// # Examples
639///
640/// ```
641/// use std::io::{Write, Result};
642///
643/// fn main() -> Result<()> {
644/// let mut w = Vec::new();
645/// writeln!(&mut w)?;
646/// writeln!(&mut w, "test")?;
647/// writeln!(&mut w, "formatted {}", "arguments")?;
648///
649/// assert_eq!(&w[..], "\ntest\nformatted arguments\n".as_bytes());
650/// Ok(())
651/// }
652/// ```
653#[macro_export]
654#[stable(feature = "rust1", since = "1.0.0")]
655#[rustc_diagnostic_item = "writeln_macro"]
656#[allow_internal_unstable(format_args_nl)]
657macro_rules! writeln {
658 ($dst:expr $(,)?) => {
659 $crate::write!($dst, "\n")
660 };
661 ($dst:expr, $($arg:tt)*) => {
662 $dst.write_fmt($crate::format_args_nl!($($arg)*))
663 };
664}
665
666/// Indicates unreachable code.
667///
668/// This is useful any time that the compiler can't determine that some code is unreachable. For
669/// example:
670///
671/// * Match arms with guard conditions.
672/// * Loops that dynamically terminate.
673/// * Iterators that dynamically terminate.
674///
675/// If the determination that the code is unreachable proves incorrect, the
676/// program immediately terminates with a [`panic!`].
677///
678/// The unsafe counterpart of this macro is the [`unreachable_unchecked`] function, which
679/// will cause undefined behavior if the code is reached.
680///
681/// [`unreachable_unchecked`]: crate::hint::unreachable_unchecked
682///
683/// # Panics
684///
685/// This will always [`panic!`] because `unreachable!` is just a shorthand for `panic!` with a
686/// fixed, specific message.
687///
688/// Like `panic!`, this macro has a second form for displaying custom values.
689///
690/// # Examples
691///
692/// Match arms:
693///
694/// ```
695/// # #[allow(dead_code)]
696/// fn foo(x: Option<i32>) {
697/// match x {
698/// Some(n) if n >= 0 => println!("Some(Non-negative)"),
699/// Some(n) if n < 0 => println!("Some(Negative)"),
700/// Some(_) => unreachable!(), // compile error if commented out
701/// None => println!("None")
702/// }
703/// }
704/// ```
705///
706/// Iterators:
707///
708/// ```
709/// # #[allow(dead_code)]
710/// fn divide_by_three(x: u32) -> u32 { // one of the poorest implementations of x/3
711/// for i in 0.. {
712/// if 3*i < i { panic!("u32 overflow"); }
713/// if x < 3*i { return i-1; }
714/// }
715/// unreachable!("The loop should always return");
716/// }
717/// ```
718#[macro_export]
719#[rustc_builtin_macro(unreachable)]
720#[allow_internal_unstable(edition_panic)]
721#[stable(feature = "rust1", since = "1.0.0")]
722#[rustc_diagnostic_item = "unreachable_macro"]
723macro_rules! unreachable {
724 // Expands to either `$crate::panic::unreachable_2015` or `$crate::panic::unreachable_2021`
725 // depending on the edition of the caller.
726 ($($arg:tt)*) => {
727 /* compiler built-in */
728 };
729}
730
731/// Indicates unimplemented code by panicking with a message of "not implemented".
732///
733/// This allows your code to type-check, which is useful if you are prototyping or
734/// implementing a trait that requires multiple methods which you don't plan to use all of.
735///
736/// The difference between `unimplemented!` and [`todo!`] is that while `todo!`
737/// conveys an intent of implementing the functionality later and the message is "not yet
738/// implemented", `unimplemented!` makes no such claims. Its message is "not implemented".
739///
740/// Also, some IDEs will mark `todo!`s.
741///
742/// # Panics
743///
744/// This will always [`panic!`] because `unimplemented!` is just a shorthand for `panic!` with a
745/// fixed, specific message.
746///
747/// Like `panic!`, this macro has a second form for displaying custom values.
748///
749/// [`todo!`]: crate::todo
750///
751/// # Examples
752///
753/// Say we have a trait `Foo`:
754///
755/// ```
756/// trait Foo {
757/// fn bar(&self) -> u8;
758/// fn baz(&self);
759/// fn qux(&self) -> Result<u64, ()>;
760/// }
761/// ```
762///
763/// We want to implement `Foo` for 'MyStruct', but for some reason it only makes sense
764/// to implement the `bar()` function. `baz()` and `qux()` will still need to be defined
765/// in our implementation of `Foo`, but we can use `unimplemented!` in their definitions
766/// to allow our code to compile.
767///
768/// We still want to have our program stop running if the unimplemented methods are
769/// reached.
770///
771/// ```
772/// # trait Foo {
773/// # fn bar(&self) -> u8;
774/// # fn baz(&self);
775/// # fn qux(&self) -> Result<u64, ()>;
776/// # }
777/// struct MyStruct;
778///
779/// impl Foo for MyStruct {
780/// fn bar(&self) -> u8 {
781/// 1 + 1
782/// }
783///
784/// fn baz(&self) {
785/// // It makes no sense to `baz` a `MyStruct`, so we have no logic here
786/// // at all.
787/// // This will display "thread 'main' panicked at 'not implemented'".
788/// unimplemented!();
789/// }
790///
791/// fn qux(&self) -> Result<u64, ()> {
792/// // We have some logic here,
793/// // We can add a message to unimplemented! to display our omission.
794/// // This will display:
795/// // "thread 'main' panicked at 'not implemented: MyStruct isn't quxable'".
796/// unimplemented!("MyStruct isn't quxable");
797/// }
798/// }
799///
800/// fn main() {
801/// let s = MyStruct;
802/// s.bar();
803/// }
804/// ```
805#[macro_export]
806#[stable(feature = "rust1", since = "1.0.0")]
807#[rustc_diagnostic_item = "unimplemented_macro"]
808#[allow_internal_unstable(panic_internals)]
809macro_rules! unimplemented {
810 () => {
811 $crate::panicking::panic("not implemented")
812 };
813 ($($arg:tt)+) => {
814 $crate::panic!("not implemented: {}", $crate::format_args!($($arg)+))
815 };
816}
817
818/// Indicates unfinished code.
819///
820/// This can be useful if you are prototyping and just
821/// want a placeholder to let your code pass type analysis.
822///
823/// The difference between [`unimplemented!`] and `todo!` is that while `todo!` conveys
824/// an intent of implementing the functionality later and the message is "not yet
825/// implemented", `unimplemented!` makes no such claims. Its message is "not implemented".
826///
827/// Also, some IDEs will mark `todo!`s.
828///
829/// # Panics
830///
831/// This will always [`panic!`] because `todo!` is just a shorthand for `panic!` with a
832/// fixed, specific message.
833///
834/// Like `panic!`, this macro has a second form for displaying custom values.
835///
836/// # Examples
837///
838/// Here's an example of some in-progress code. We have a trait `Foo`:
839///
840/// ```
841/// trait Foo {
842/// fn bar(&self) -> u8;
843/// fn baz(&self);
844/// fn qux(&self) -> Result<u64, ()>;
845/// }
846/// ```
847///
848/// We want to implement `Foo` on one of our types, but we also want to work on
849/// just `bar()` first. In order for our code to compile, we need to implement
850/// `baz()` and `qux()`, so we can use `todo!`:
851///
852/// ```
853/// # trait Foo {
854/// # fn bar(&self) -> u8;
855/// # fn baz(&self);
856/// # fn qux(&self) -> Result<u64, ()>;
857/// # }
858/// struct MyStruct;
859///
860/// impl Foo for MyStruct {
861/// fn bar(&self) -> u8 {
862/// 1 + 1
863/// }
864///
865/// fn baz(&self) {
866/// // Let's not worry about implementing baz() for now
867/// todo!();
868/// }
869///
870/// fn qux(&self) -> Result<u64, ()> {
871/// // We can add a message to todo! to display our omission.
872/// // This will display:
873/// // "thread 'main' panicked at 'not yet implemented: MyStruct is not yet quxable'".
874/// todo!("MyStruct is not yet quxable");
875/// }
876/// }
877///
878/// fn main() {
879/// let s = MyStruct;
880/// s.bar();
881///
882/// // We aren't even using baz() or qux(), so this is fine.
883/// }
884/// ```
885#[macro_export]
886#[stable(feature = "todo_macro", since = "1.40.0")]
887#[rustc_diagnostic_item = "todo_macro"]
888#[allow_internal_unstable(panic_internals)]
889macro_rules! todo {
890 () => {
891 $crate::panicking::panic("not yet implemented")
892 };
893 ($($arg:tt)+) => {
894 $crate::panic!("not yet implemented: {}", $crate::format_args!($($arg)+))
895 };
896}
897
898/// Definitions of built-in macros.
899///
900/// Most of the macro properties (stability, visibility, etc.) are taken from the source code here,
901/// with exception of expansion functions transforming macro inputs into outputs,
902/// those functions are provided by the compiler.
903pub(crate) mod builtin {
904
905 /// Causes compilation to fail with the given error message when encountered.
906 ///
907 /// This macro should be used when a crate uses a conditional compilation strategy to provide
908 /// better error messages for erroneous conditions. It's the compiler-level form of [`panic!`],
909 /// but emits an error during *compilation* rather than at *runtime*.
910 ///
911 /// # Examples
912 ///
913 /// Two such examples are macros and `#[cfg]` environments.
914 ///
915 /// Emit a better compiler error if a macro is passed invalid values. Without the final branch,
916 /// the compiler would still emit an error, but the error's message would not mention the two
917 /// valid values.
918 ///
919 /// ```compile_fail
920 /// macro_rules! give_me_foo_or_bar {
921 /// (foo) => {};
922 /// (bar) => {};
923 /// ($x:ident) => {
924 /// compile_error!("This macro only accepts `foo` or `bar`");
925 /// }
926 /// }
927 ///
928 /// give_me_foo_or_bar!(neither);
929 /// // ^ will fail at compile time with message "This macro only accepts `foo` or `bar`"
930 /// ```
931 ///
932 /// Emit a compiler error if one of a number of features isn't available.
933 ///
934 /// ```compile_fail
935 /// #[cfg(not(any(feature = "foo", feature = "bar")))]
936 /// compile_error!("Either feature \"foo\" or \"bar\" must be enabled for this crate.");
937 /// ```
938 #[stable(feature = "compile_error_macro", since = "1.20.0")]
939 #[rustc_builtin_macro]
940 #[macro_export]
941 macro_rules! compile_error {
942 ($msg:expr $(,)?) => {{ /* compiler built-in */ }};
943 }
944
945 /// Constructs parameters for the other string-formatting macros.
946 ///
947 /// This macro functions by taking a formatting string literal containing
948 /// `{}` for each additional argument passed. `format_args!` prepares the
949 /// additional parameters to ensure the output can be interpreted as a string
950 /// and canonicalizes the arguments into a single type. Any value that implements
951 /// the [`Display`] trait can be passed to `format_args!`, as can any
952 /// [`Debug`] implementation be passed to a `{:?}` within the formatting string.
953 ///
954 /// This macro produces a value of type [`fmt::Arguments`]. This value can be
955 /// passed to the macros within [`std::fmt`] for performing useful redirection.
956 /// All other formatting macros ([`format!`], [`write!`], [`println!`], etc) are
957 /// proxied through this one. `format_args!`, unlike its derived macros, avoids
958 /// heap allocations.
959 ///
960 /// You can use the [`fmt::Arguments`] value that `format_args!` returns
961 /// in `Debug` and `Display` contexts as seen below. The example also shows
962 /// that `Debug` and `Display` format to the same thing: the interpolated
963 /// format string in `format_args!`.
964 ///
965 /// ```rust
966 /// let debug = format!("{:?}", format_args!("{} foo {:?}", 1, 2));
967 /// let display = format!("{}", format_args!("{} foo {:?}", 1, 2));
968 /// assert_eq!("1 foo 2", display);
969 /// assert_eq!(display, debug);
970 /// ```
971 ///
972 /// See [the formatting documentation in `std::fmt`](../std/fmt/index.html)
973 /// for details of the macro argument syntax, and further information.
974 ///
975 /// [`Display`]: crate::fmt::Display
976 /// [`Debug`]: crate::fmt::Debug
977 /// [`fmt::Arguments`]: crate::fmt::Arguments
978 /// [`std::fmt`]: ../std/fmt/index.html
979 /// [`format!`]: ../std/macro.format.html
980 /// [`println!`]: ../std/macro.println.html
981 ///
982 /// # Examples
983 ///
984 /// ```
985 /// use std::fmt;
986 ///
987 /// let s = fmt::format(format_args!("hello {}", "world"));
988 /// assert_eq!(s, format!("hello {}", "world"));
989 /// ```
990 ///
991 /// # Lifetime limitation
992 ///
993 /// Except when no formatting arguments are used,
994 /// the produced `fmt::Arguments` value borrows temporary values,
995 /// which means it can only be used within the same expression
996 /// and cannot be stored for later use.
997 /// This is a known limitation, see [#92698](https://github.com/rust-lang/rust/issues/92698).
998 #[stable(feature = "rust1", since = "1.0.0")]
999 #[rustc_diagnostic_item = "format_args_macro"]
1000 #[allow_internal_unsafe]
1001 #[allow_internal_unstable(fmt_internals)]
1002 #[rustc_builtin_macro]
1003 #[macro_export]
1004 macro_rules! format_args {
1005 ($fmt:expr) => {{ /* compiler built-in */ }};
1006 ($fmt:expr, $($args:tt)*) => {{ /* compiler built-in */ }};
1007 }
1008
1009 /// Same as [`format_args`], but can be used in some const contexts.
1010 ///
1011 /// This macro is used by the panic macros for the `const_panic` feature.
1012 ///
1013 /// This macro will be removed once `format_args` is allowed in const contexts.
1014 #[unstable(feature = "const_format_args", issue = "none")]
1015 #[allow_internal_unstable(fmt_internals, const_fmt_arguments_new)]
1016 #[rustc_builtin_macro]
1017 #[macro_export]
1018 macro_rules! const_format_args {
1019 ($fmt:expr) => {{ /* compiler built-in */ }};
1020 ($fmt:expr, $($args:tt)*) => {{ /* compiler built-in */ }};
1021 }
1022
1023 /// Same as [`format_args`], but adds a newline in the end.
1024 #[unstable(
1025 feature = "format_args_nl",
1026 issue = "none",
1027 reason = "`format_args_nl` is only for internal \
1028 language use and is subject to change"
1029 )]
1030 #[allow_internal_unstable(fmt_internals)]
1031 #[rustc_builtin_macro]
1032 #[macro_export]
1033 macro_rules! format_args_nl {
1034 ($fmt:expr) => {{ /* compiler built-in */ }};
1035 ($fmt:expr, $($args:tt)*) => {{ /* compiler built-in */ }};
1036 }
1037
1038 /// Inspects an environment variable at compile time.
1039 ///
1040 /// This macro will expand to the value of the named environment variable at
1041 /// compile time, yielding an expression of type `&'static str`. Use
1042 /// [`std::env::var`] instead if you want to read the value at runtime.
1043 ///
1044 /// [`std::env::var`]: ../std/env/fn.var.html
1045 ///
1046 /// If the environment variable is not defined, then a compilation error
1047 /// will be emitted. To not emit a compile error, use the [`option_env!`]
1048 /// macro instead. A compilation error will also be emitted if the
1049 /// environment variable is not a valid Unicode string.
1050 ///
1051 /// # Examples
1052 ///
1053 /// ```
1054 /// let path: &'static str = env!("PATH");
1055 /// println!("the $PATH variable at the time of compiling was: {path}");
1056 /// ```
1057 ///
1058 /// You can customize the error message by passing a string as the second
1059 /// parameter:
1060 ///
1061 /// ```compile_fail
1062 /// let doc: &'static str = env!("documentation", "what's that?!");
1063 /// ```
1064 ///
1065 /// If the `documentation` environment variable is not defined, you'll get
1066 /// the following error:
1067 ///
1068 /// ```text
1069 /// error: what's that?!
1070 /// ```
1071 #[stable(feature = "rust1", since = "1.0.0")]
1072 #[rustc_builtin_macro]
1073 #[macro_export]
1074 #[rustc_diagnostic_item = "env_macro"] // useful for external lints
1075 macro_rules! env {
1076 ($name:expr $(,)?) => {{ /* compiler built-in */ }};
1077 ($name:expr, $error_msg:expr $(,)?) => {{ /* compiler built-in */ }};
1078 }
1079
1080 /// Optionally inspects an environment variable at compile time.
1081 ///
1082 /// If the named environment variable is present at compile time, this will
1083 /// expand into an expression of type `Option<&'static str>` whose value is
1084 /// `Some` of the value of the environment variable (a compilation error
1085 /// will be emitted if the environment variable is not a valid Unicode
1086 /// string). If the environment variable is not present, then this will
1087 /// expand to `None`. See [`Option<T>`][Option] for more information on this
1088 /// type. Use [`std::env::var`] instead if you want to read the value at
1089 /// runtime.
1090 ///
1091 /// [`std::env::var`]: ../std/env/fn.var.html
1092 ///
1093 /// A compile time error is only emitted when using this macro if the
1094 /// environment variable exists and is not a valid Unicode string. To also
1095 /// emit a compile error if the environment variable is not present, use the
1096 /// [`env!`] macro instead.
1097 ///
1098 /// # Examples
1099 ///
1100 /// ```
1101 /// let key: Option<&'static str> = option_env!("SECRET_KEY");
1102 /// println!("the secret key might be: {key:?}");
1103 /// ```
1104 #[stable(feature = "rust1", since = "1.0.0")]
1105 #[rustc_builtin_macro]
1106 #[macro_export]
1107 #[rustc_diagnostic_item = "option_env_macro"] // useful for external lints
1108 macro_rules! option_env {
1109 ($name:expr $(,)?) => {{ /* compiler built-in */ }};
1110 }
1111
1112 /// Concatenates identifiers into one identifier.
1113 ///
1114 /// This macro takes any number of comma-separated identifiers, and
1115 /// concatenates them all into one, yielding an expression which is a new
1116 /// identifier. Note that hygiene makes it such that this macro cannot
1117 /// capture local variables. Also, as a general rule, macros are only
1118 /// allowed in item, statement or expression position. That means while
1119 /// you may use this macro for referring to existing variables, functions or
1120 /// modules etc, you cannot define a new one with it.
1121 ///
1122 /// # Examples
1123 ///
1124 /// ```
1125 /// #![feature(concat_idents)]
1126 ///
1127 /// # fn main() {
1128 /// fn foobar() -> u32 { 23 }
1129 ///
1130 /// let f = concat_idents!(foo, bar);
1131 /// println!("{}", f());
1132 ///
1133 /// // fn concat_idents!(new, fun, name) { } // not usable in this way!
1134 /// # }
1135 /// ```
1136 #[unstable(
1137 feature = "concat_idents",
1138 issue = "29599",
1139 reason = "`concat_idents` is not stable enough for use and is subject to change"
1140 )]
1141 #[deprecated(
1142 since = "1.88.0",
1143 note = "use `${concat(...)}` with the `macro_metavar_expr_concat` feature instead"
1144 )]
1145 #[rustc_builtin_macro]
1146 #[macro_export]
1147 macro_rules! concat_idents {
1148 ($($e:ident),+ $(,)?) => {{ /* compiler built-in */ }};
1149 }
1150
1151 /// Concatenates literals into a byte slice.
1152 ///
1153 /// This macro takes any number of comma-separated literals, and concatenates them all into
1154 /// one, yielding an expression of type `&[u8; _]`, which represents all of the literals
1155 /// concatenated left-to-right. The literals passed can be any combination of:
1156 ///
1157 /// - byte literals (`b'r'`)
1158 /// - byte strings (`b"Rust"`)
1159 /// - arrays of bytes/numbers (`[b'A', 66, b'C']`)
1160 ///
1161 /// # Examples
1162 ///
1163 /// ```
1164 /// #![feature(concat_bytes)]
1165 ///
1166 /// # fn main() {
1167 /// let s: &[u8; 6] = concat_bytes!(b'A', b"BC", [68, b'E', 70]);
1168 /// assert_eq!(s, b"ABCDEF");
1169 /// # }
1170 /// ```
1171 #[unstable(feature = "concat_bytes", issue = "87555")]
1172 #[rustc_builtin_macro]
1173 #[macro_export]
1174 macro_rules! concat_bytes {
1175 ($($e:literal),+ $(,)?) => {{ /* compiler built-in */ }};
1176 }
1177
1178 /// Concatenates literals into a static string slice.
1179 ///
1180 /// This macro takes any number of comma-separated literals, yielding an
1181 /// expression of type `&'static str` which represents all of the literals
1182 /// concatenated left-to-right.
1183 ///
1184 /// Integer and floating point literals are [stringified](core::stringify) in order to be
1185 /// concatenated.
1186 ///
1187 /// # Examples
1188 ///
1189 /// ```
1190 /// let s = concat!("test", 10, 'b', true);
1191 /// assert_eq!(s, "test10btrue");
1192 /// ```
1193 #[stable(feature = "rust1", since = "1.0.0")]
1194 #[rustc_builtin_macro]
1195 #[macro_export]
1196 macro_rules! concat {
1197 ($($e:expr),* $(,)?) => {{ /* compiler built-in */ }};
1198 }
1199
1200 /// Expands to the line number on which it was invoked.
1201 ///
1202 /// With [`column!`] and [`file!`], these macros provide debugging information for
1203 /// developers about the location within the source.
1204 ///
1205 /// The expanded expression has type `u32` and is 1-based, so the first line
1206 /// in each file evaluates to 1, the second to 2, etc. This is consistent
1207 /// with error messages by common compilers or popular editors.
1208 /// The returned line is *not necessarily* the line of the `line!` invocation itself,
1209 /// but rather the first macro invocation leading up to the invocation
1210 /// of the `line!` macro.
1211 ///
1212 /// # Examples
1213 ///
1214 /// ```
1215 /// let current_line = line!();
1216 /// println!("defined on line: {current_line}");
1217 /// ```
1218 #[stable(feature = "rust1", since = "1.0.0")]
1219 #[rustc_builtin_macro]
1220 #[macro_export]
1221 macro_rules! line {
1222 () => {
1223 /* compiler built-in */
1224 };
1225 }
1226
1227 /// Expands to the column number at which it was invoked.
1228 ///
1229 /// With [`line!`] and [`file!`], these macros provide debugging information for
1230 /// developers about the location within the source.
1231 ///
1232 /// The expanded expression has type `u32` and is 1-based, so the first column
1233 /// in each line evaluates to 1, the second to 2, etc. This is consistent
1234 /// with error messages by common compilers or popular editors.
1235 /// The returned column is *not necessarily* the line of the `column!` invocation itself,
1236 /// but rather the first macro invocation leading up to the invocation
1237 /// of the `column!` macro.
1238 ///
1239 /// # Examples
1240 ///
1241 /// ```
1242 /// let current_col = column!();
1243 /// println!("defined on column: {current_col}");
1244 /// ```
1245 ///
1246 /// `column!` counts Unicode code points, not bytes or graphemes. As a result, the first two
1247 /// invocations return the same value, but the third does not.
1248 ///
1249 /// ```
1250 /// let a = ("foobar", column!()).1;
1251 /// let b = ("人之初性本善", column!()).1;
1252 /// let c = ("f̅o̅o̅b̅a̅r̅", column!()).1; // Uses combining overline (U+0305)
1253 ///
1254 /// assert_eq!(a, b);
1255 /// assert_ne!(b, c);
1256 /// ```
1257 #[stable(feature = "rust1", since = "1.0.0")]
1258 #[rustc_builtin_macro]
1259 #[macro_export]
1260 macro_rules! column {
1261 () => {
1262 /* compiler built-in */
1263 };
1264 }
1265
1266 /// Expands to the file name in which it was invoked.
1267 ///
1268 /// With [`line!`] and [`column!`], these macros provide debugging information for
1269 /// developers about the location within the source.
1270 ///
1271 /// The expanded expression has type `&'static str`, and the returned file
1272 /// is not the invocation of the `file!` macro itself, but rather the
1273 /// first macro invocation leading up to the invocation of the `file!`
1274 /// macro.
1275 ///
1276 /// The file name is derived from the crate root's source path passed to the Rust compiler
1277 /// and the sequence the compiler takes to get from the crate root to the
1278 /// module containing `file!`, modified by any flags passed to the Rust compiler (e.g.
1279 /// `--remap-path-prefix`). If the crate's source path is relative, the initial base
1280 /// directory will be the working directory of the Rust compiler. For example, if the source
1281 /// path passed to the compiler is `./src/lib.rs` which has a `mod foo;` with a source path of
1282 /// `src/foo/mod.rs`, then calling `file!` inside `mod foo;` will return `./src/foo/mod.rs`.
1283 ///
1284 /// Future compiler options might make further changes to the behavior of `file!`,
1285 /// including potentially making it entirely empty. Code (e.g. test libraries)
1286 /// relying on `file!` producing an openable file path would be incompatible
1287 /// with such options, and might wish to recommend not using those options.
1288 ///
1289 /// # Examples
1290 ///
1291 /// ```
1292 /// let this_file = file!();
1293 /// println!("defined in file: {this_file}");
1294 /// ```
1295 #[stable(feature = "rust1", since = "1.0.0")]
1296 #[rustc_builtin_macro]
1297 #[macro_export]
1298 macro_rules! file {
1299 () => {
1300 /* compiler built-in */
1301 };
1302 }
1303
1304 /// Stringifies its arguments.
1305 ///
1306 /// This macro will yield an expression of type `&'static str` which is the
1307 /// stringification of all the tokens passed to the macro. No restrictions
1308 /// are placed on the syntax of the macro invocation itself.
1309 ///
1310 /// Note that the expanded results of the input tokens may change in the
1311 /// future. You should be careful if you rely on the output.
1312 ///
1313 /// # Examples
1314 ///
1315 /// ```
1316 /// let one_plus_one = stringify!(1 + 1);
1317 /// assert_eq!(one_plus_one, "1 + 1");
1318 /// ```
1319 #[stable(feature = "rust1", since = "1.0.0")]
1320 #[rustc_builtin_macro]
1321 #[macro_export]
1322 macro_rules! stringify {
1323 ($($t:tt)*) => {
1324 /* compiler built-in */
1325 };
1326 }
1327
1328 /// Includes a UTF-8 encoded file as a string.
1329 ///
1330 /// The file is located relative to the current file (similarly to how
1331 /// modules are found). The provided path is interpreted in a platform-specific
1332 /// way at compile time. So, for instance, an invocation with a Windows path
1333 /// containing backslashes `\` would not compile correctly on Unix.
1334 ///
1335 /// This macro will yield an expression of type `&'static str` which is the
1336 /// contents of the file.
1337 ///
1338 /// # Examples
1339 ///
1340 /// Assume there are two files in the same directory with the following
1341 /// contents:
1342 ///
1343 /// File 'spanish.in':
1344 ///
1345 /// ```text
1346 /// adiós
1347 /// ```
1348 ///
1349 /// File 'main.rs':
1350 ///
1351 /// ```ignore (cannot-doctest-external-file-dependency)
1352 /// fn main() {
1353 /// let my_str = include_str!("spanish.in");
1354 /// assert_eq!(my_str, "adiós\n");
1355 /// print!("{my_str}");
1356 /// }
1357 /// ```
1358 ///
1359 /// Compiling 'main.rs' and running the resulting binary will print "adiós".
1360 #[stable(feature = "rust1", since = "1.0.0")]
1361 #[rustc_builtin_macro]
1362 #[macro_export]
1363 #[rustc_diagnostic_item = "include_str_macro"]
1364 macro_rules! include_str {
1365 ($file:expr $(,)?) => {{ /* compiler built-in */ }};
1366 }
1367
1368 /// Includes a file as a reference to a byte array.
1369 ///
1370 /// The file is located relative to the current file (similarly to how
1371 /// modules are found). The provided path is interpreted in a platform-specific
1372 /// way at compile time. So, for instance, an invocation with a Windows path
1373 /// containing backslashes `\` would not compile correctly on Unix.
1374 ///
1375 /// This macro will yield an expression of type `&'static [u8; N]` which is
1376 /// the contents of the file.
1377 ///
1378 /// # Examples
1379 ///
1380 /// Assume there are two files in the same directory with the following
1381 /// contents:
1382 ///
1383 /// File 'spanish.in':
1384 ///
1385 /// ```text
1386 /// adiós
1387 /// ```
1388 ///
1389 /// File 'main.rs':
1390 ///
1391 /// ```ignore (cannot-doctest-external-file-dependency)
1392 /// fn main() {
1393 /// let bytes = include_bytes!("spanish.in");
1394 /// assert_eq!(bytes, b"adi\xc3\xb3s\n");
1395 /// print!("{}", String::from_utf8_lossy(bytes));
1396 /// }
1397 /// ```
1398 ///
1399 /// Compiling 'main.rs' and running the resulting binary will print "adiós".
1400 #[stable(feature = "rust1", since = "1.0.0")]
1401 #[rustc_builtin_macro]
1402 #[macro_export]
1403 #[rustc_diagnostic_item = "include_bytes_macro"]
1404 macro_rules! include_bytes {
1405 ($file:expr $(,)?) => {{ /* compiler built-in */ }};
1406 }
1407
1408 /// Expands to a string that represents the current module path.
1409 ///
1410 /// The current module path can be thought of as the hierarchy of modules
1411 /// leading back up to the crate root. The first component of the path
1412 /// returned is the name of the crate currently being compiled.
1413 ///
1414 /// # Examples
1415 ///
1416 /// ```
1417 /// mod test {
1418 /// pub fn foo() {
1419 /// assert!(module_path!().ends_with("test"));
1420 /// }
1421 /// }
1422 ///
1423 /// test::foo();
1424 /// ```
1425 #[stable(feature = "rust1", since = "1.0.0")]
1426 #[rustc_builtin_macro]
1427 #[macro_export]
1428 macro_rules! module_path {
1429 () => {
1430 /* compiler built-in */
1431 };
1432 }
1433
1434 /// Evaluates boolean combinations of configuration flags at compile-time.
1435 ///
1436 /// In addition to the `#[cfg]` attribute, this macro is provided to allow
1437 /// boolean expression evaluation of configuration flags. This frequently
1438 /// leads to less duplicated code.
1439 ///
1440 /// The syntax given to this macro is the same syntax as the [`cfg`]
1441 /// attribute.
1442 ///
1443 /// `cfg!`, unlike `#[cfg]`, does not remove any code and only evaluates to true or false. For
1444 /// example, all blocks in an if/else expression need to be valid when `cfg!` is used for
1445 /// the condition, regardless of what `cfg!` is evaluating.
1446 ///
1447 /// [`cfg`]: ../reference/conditional-compilation.html#the-cfg-attribute
1448 ///
1449 /// # Examples
1450 ///
1451 /// ```
1452 /// let my_directory = if cfg!(windows) {
1453 /// "windows-specific-directory"
1454 /// } else {
1455 /// "unix-directory"
1456 /// };
1457 /// ```
1458 #[stable(feature = "rust1", since = "1.0.0")]
1459 #[rustc_builtin_macro]
1460 #[macro_export]
1461 macro_rules! cfg {
1462 ($($cfg:tt)*) => {
1463 /* compiler built-in */
1464 };
1465 }
1466
1467 /// Parses a file as an expression or an item according to the context.
1468 ///
1469 /// **Warning**: For multi-file Rust projects, the `include!` macro is probably not what you
1470 /// are looking for. Usually, multi-file Rust projects use
1471 /// [modules](https://doc.rust-lang.org/reference/items/modules.html). Multi-file projects and
1472 /// modules are explained in the Rust-by-Example book
1473 /// [here](https://doc.rust-lang.org/rust-by-example/mod/split.html) and the module system is
1474 /// explained in the Rust Book
1475 /// [here](https://doc.rust-lang.org/book/ch07-02-defining-modules-to-control-scope-and-privacy.html).
1476 ///
1477 /// The included file is placed in the surrounding code
1478 /// [unhygienically](https://doc.rust-lang.org/reference/macros-by-example.html#hygiene). If
1479 /// the included file is parsed as an expression and variables or functions share names across
1480 /// both files, it could result in variables or functions being different from what the
1481 /// included file expected.
1482 ///
1483 /// The included file is located relative to the current file (similarly to how modules are
1484 /// found). The provided path is interpreted in a platform-specific way at compile time. So,
1485 /// for instance, an invocation with a Windows path containing backslashes `\` would not
1486 /// compile correctly on Unix.
1487 ///
1488 /// # Uses
1489 ///
1490 /// The `include!` macro is primarily used for two purposes. It is used to include
1491 /// documentation that is written in a separate file and it is used to include [build artifacts
1492 /// usually as a result from the `build.rs`
1493 /// script](https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script).
1494 ///
1495 /// When using the `include` macro to include stretches of documentation, remember that the
1496 /// included file still needs to be a valid Rust syntax. It is also possible to
1497 /// use the [`include_str`] macro as `#![doc = include_str!("...")]` (at the module level) or
1498 /// `#[doc = include_str!("...")]` (at the item level) to include documentation from a plain
1499 /// text or markdown file.
1500 ///
1501 /// # Examples
1502 ///
1503 /// Assume there are two files in the same directory with the following contents:
1504 ///
1505 /// File 'monkeys.in':
1506 ///
1507 /// ```ignore (only-for-syntax-highlight)
1508 /// ['🙈', '🙊', '🙉']
1509 /// .iter()
1510 /// .cycle()
1511 /// .take(6)
1512 /// .collect::<String>()
1513 /// ```
1514 ///
1515 /// File 'main.rs':
1516 ///
1517 /// ```ignore (cannot-doctest-external-file-dependency)
1518 /// fn main() {
1519 /// let my_string = include!("monkeys.in");
1520 /// assert_eq!("🙈🙊🙉🙈🙊🙉", my_string);
1521 /// println!("{my_string}");
1522 /// }
1523 /// ```
1524 ///
1525 /// Compiling 'main.rs' and running the resulting binary will print
1526 /// "🙈🙊🙉🙈🙊🙉".
1527 #[stable(feature = "rust1", since = "1.0.0")]
1528 #[rustc_builtin_macro]
1529 #[macro_export]
1530 #[rustc_diagnostic_item = "include_macro"] // useful for external lints
1531 macro_rules! include {
1532 ($file:expr $(,)?) => {{ /* compiler built-in */ }};
1533 }
1534
1535 /// This macro uses forward-mode automatic differentiation to generate a new function.
1536 /// It may only be applied to a function. The new function will compute the derivative
1537 /// of the function to which the macro was applied.
1538 ///
1539 /// The expected usage syntax is:
1540 /// `#[autodiff_forward(NAME, INPUT_ACTIVITIES, OUTPUT_ACTIVITY)]`
1541 ///
1542 /// - `NAME`: A string that represents a valid function name.
1543 /// - `INPUT_ACTIVITIES`: Specifies one valid activity for each input parameter.
1544 /// - `OUTPUT_ACTIVITY`: Must not be set if the function implicitly returns nothing
1545 /// (or explicitly returns `-> ()`). Otherwise, it must be set to one of the allowed activities.
1546 #[unstable(feature = "autodiff", issue = "124509")]
1547 #[allow_internal_unstable(rustc_attrs)]
1548 #[rustc_builtin_macro]
1549 pub macro autodiff_forward($item:item) {
1550 /* compiler built-in */
1551 }
1552
1553 /// This macro uses reverse-mode automatic differentiation to generate a new function.
1554 /// It may only be applied to a function. The new function will compute the derivative
1555 /// of the function to which the macro was applied.
1556 ///
1557 /// The expected usage syntax is:
1558 /// `#[autodiff_reverse(NAME, INPUT_ACTIVITIES, OUTPUT_ACTIVITY)]`
1559 ///
1560 /// - `NAME`: A string that represents a valid function name.
1561 /// - `INPUT_ACTIVITIES`: Specifies one valid activity for each input parameter.
1562 /// - `OUTPUT_ACTIVITY`: Must not be set if the function implicitly returns nothing
1563 /// (or explicitly returns `-> ()`). Otherwise, it must be set to one of the allowed activities.
1564 #[unstable(feature = "autodiff", issue = "124509")]
1565 #[allow_internal_unstable(rustc_attrs)]
1566 #[rustc_builtin_macro]
1567 pub macro autodiff_reverse($item:item) {
1568 /* compiler built-in */
1569 }
1570
1571 /// Asserts that a boolean expression is `true` at runtime.
1572 ///
1573 /// This will invoke the [`panic!`] macro if the provided expression cannot be
1574 /// evaluated to `true` at runtime.
1575 ///
1576 /// # Uses
1577 ///
1578 /// Assertions are always checked in both debug and release builds, and cannot
1579 /// be disabled. See [`debug_assert!`] for assertions that are not enabled in
1580 /// release builds by default.
1581 ///
1582 /// Unsafe code may rely on `assert!` to enforce run-time invariants that, if
1583 /// violated could lead to unsafety.
1584 ///
1585 /// Other use-cases of `assert!` include testing and enforcing run-time
1586 /// invariants in safe code (whose violation cannot result in unsafety).
1587 ///
1588 /// # Custom Messages
1589 ///
1590 /// This macro has a second form, where a custom panic message can
1591 /// be provided with or without arguments for formatting. See [`std::fmt`]
1592 /// for syntax for this form. Expressions used as format arguments will only
1593 /// be evaluated if the assertion fails.
1594 ///
1595 /// [`std::fmt`]: ../std/fmt/index.html
1596 ///
1597 /// # Examples
1598 ///
1599 /// ```
1600 /// // the panic message for these assertions is the stringified value of the
1601 /// // expression given.
1602 /// assert!(true);
1603 ///
1604 /// fn some_computation() -> bool { true } // a very simple function
1605 ///
1606 /// assert!(some_computation());
1607 ///
1608 /// // assert with a custom message
1609 /// let x = true;
1610 /// assert!(x, "x wasn't true!");
1611 ///
1612 /// let a = 3; let b = 27;
1613 /// assert!(a + b == 30, "a = {}, b = {}", a, b);
1614 /// ```
1615 #[stable(feature = "rust1", since = "1.0.0")]
1616 #[rustc_builtin_macro]
1617 #[macro_export]
1618 #[rustc_diagnostic_item = "assert_macro"]
1619 #[allow_internal_unstable(
1620 core_intrinsics,
1621 panic_internals,
1622 edition_panic,
1623 generic_assert_internals
1624 )]
1625 macro_rules! assert {
1626 ($cond:expr $(,)?) => {{ /* compiler built-in */ }};
1627 ($cond:expr, $($arg:tt)+) => {{ /* compiler built-in */ }};
1628 }
1629
1630 /// Prints passed tokens into the standard output.
1631 #[unstable(
1632 feature = "log_syntax",
1633 issue = "29598",
1634 reason = "`log_syntax!` is not stable enough for use and is subject to change"
1635 )]
1636 #[rustc_builtin_macro]
1637 #[macro_export]
1638 macro_rules! log_syntax {
1639 ($($arg:tt)*) => {
1640 /* compiler built-in */
1641 };
1642 }
1643
1644 /// Enables or disables tracing functionality used for debugging other macros.
1645 #[unstable(
1646 feature = "trace_macros",
1647 issue = "29598",
1648 reason = "`trace_macros` is not stable enough for use and is subject to change"
1649 )]
1650 #[rustc_builtin_macro]
1651 #[macro_export]
1652 macro_rules! trace_macros {
1653 (true) => {{ /* compiler built-in */ }};
1654 (false) => {{ /* compiler built-in */ }};
1655 }
1656
1657 /// Attribute macro used to apply derive macros.
1658 ///
1659 /// See [the reference] for more info.
1660 ///
1661 /// [the reference]: ../../../reference/attributes/derive.html
1662 #[stable(feature = "rust1", since = "1.0.0")]
1663 #[rustc_builtin_macro]
1664 pub macro derive($item:item) {
1665 /* compiler built-in */
1666 }
1667
1668 /// Attribute macro used to apply derive macros for implementing traits
1669 /// in a const context.
1670 ///
1671 /// See [the reference] for more info.
1672 ///
1673 /// [the reference]: ../../../reference/attributes/derive.html
1674 #[unstable(feature = "derive_const", issue = "none")]
1675 #[rustc_builtin_macro]
1676 pub macro derive_const($item:item) {
1677 /* compiler built-in */
1678 }
1679
1680 /// Attribute macro applied to a function to turn it into a unit test.
1681 ///
1682 /// See [the reference] for more info.
1683 ///
1684 /// [the reference]: ../../../reference/attributes/testing.html#the-test-attribute
1685 #[stable(feature = "rust1", since = "1.0.0")]
1686 #[allow_internal_unstable(test, rustc_attrs, coverage_attribute)]
1687 #[rustc_builtin_macro]
1688 pub macro test($item:item) {
1689 /* compiler built-in */
1690 }
1691
1692 /// Attribute macro applied to a function to turn it into a benchmark test.
1693 #[unstable(
1694 feature = "test",
1695 issue = "50297",
1696 reason = "`bench` is a part of custom test frameworks which are unstable"
1697 )]
1698 #[allow_internal_unstable(test, rustc_attrs, coverage_attribute)]
1699 #[rustc_builtin_macro]
1700 pub macro bench($item:item) {
1701 /* compiler built-in */
1702 }
1703
1704 /// An implementation detail of the `#[test]` and `#[bench]` macros.
1705 #[unstable(
1706 feature = "custom_test_frameworks",
1707 issue = "50297",
1708 reason = "custom test frameworks are an unstable feature"
1709 )]
1710 #[allow_internal_unstable(test, rustc_attrs)]
1711 #[rustc_builtin_macro]
1712 pub macro test_case($item:item) {
1713 /* compiler built-in */
1714 }
1715
1716 /// Attribute macro applied to a static to register it as a global allocator.
1717 ///
1718 /// See also [`std::alloc::GlobalAlloc`](../../../std/alloc/trait.GlobalAlloc.html).
1719 #[stable(feature = "global_allocator", since = "1.28.0")]
1720 #[allow_internal_unstable(rustc_attrs)]
1721 #[rustc_builtin_macro]
1722 pub macro global_allocator($item:item) {
1723 /* compiler built-in */
1724 }
1725
1726 /// Attribute macro applied to a function to give it a post-condition.
1727 ///
1728 /// The attribute carries an argument token-tree which is
1729 /// eventually parsed as a unary closure expression that is
1730 /// invoked on a reference to the return value.
1731 #[unstable(feature = "contracts", issue = "128044")]
1732 #[allow_internal_unstable(contracts_internals)]
1733 #[rustc_builtin_macro]
1734 pub macro contracts_ensures($item:item) {
1735 /* compiler built-in */
1736 }
1737
1738 /// Attribute macro applied to a function to give it a precondition.
1739 ///
1740 /// The attribute carries an argument token-tree which is
1741 /// eventually parsed as an boolean expression with access to the
1742 /// function's formal parameters
1743 #[unstable(feature = "contracts", issue = "128044")]
1744 #[allow_internal_unstable(contracts_internals)]
1745 #[rustc_builtin_macro]
1746 pub macro contracts_requires($item:item) {
1747 /* compiler built-in */
1748 }
1749
1750 /// Attribute macro applied to a function to register it as a handler for allocation failure.
1751 ///
1752 /// See also [`std::alloc::handle_alloc_error`](../../../std/alloc/fn.handle_alloc_error.html).
1753 #[unstable(feature = "alloc_error_handler", issue = "51540")]
1754 #[allow_internal_unstable(rustc_attrs)]
1755 #[rustc_builtin_macro]
1756 pub macro alloc_error_handler($item:item) {
1757 /* compiler built-in */
1758 }
1759
1760 /// Keeps the item it's applied to if the passed path is accessible, and removes it otherwise.
1761 #[unstable(
1762 feature = "cfg_accessible",
1763 issue = "64797",
1764 reason = "`cfg_accessible` is not fully implemented"
1765 )]
1766 #[rustc_builtin_macro]
1767 pub macro cfg_accessible($item:item) {
1768 /* compiler built-in */
1769 }
1770
1771 /// Expands all `#[cfg]` and `#[cfg_attr]` attributes in the code fragment it's applied to.
1772 #[unstable(
1773 feature = "cfg_eval",
1774 issue = "82679",
1775 reason = "`cfg_eval` is a recently implemented feature"
1776 )]
1777 #[rustc_builtin_macro]
1778 pub macro cfg_eval($($tt:tt)*) {
1779 /* compiler built-in */
1780 }
1781
1782 /// Provide a list of type aliases and other opaque-type-containing type definitions
1783 /// to an item with a body. This list will be used in that body to define opaque
1784 /// types' hidden types.
1785 /// Can only be applied to things that have bodies.
1786 #[unstable(
1787 feature = "type_alias_impl_trait",
1788 issue = "63063",
1789 reason = "`type_alias_impl_trait` has open design concerns"
1790 )]
1791 #[rustc_builtin_macro]
1792 pub macro define_opaque($($tt:tt)*) {
1793 /* compiler built-in */
1794 }
1795
1796 /// Unstable placeholder for type ascription.
1797 #[allow_internal_unstable(builtin_syntax)]
1798 #[unstable(
1799 feature = "type_ascription",
1800 issue = "23416",
1801 reason = "placeholder syntax for type ascription"
1802 )]
1803 #[rustfmt::skip]
1804 pub macro type_ascribe($expr:expr, $ty:ty) {
1805 builtin # type_ascribe($expr, $ty)
1806 }
1807
1808 /// Unstable placeholder for deref patterns.
1809 #[allow_internal_unstable(builtin_syntax)]
1810 #[unstable(
1811 feature = "deref_patterns",
1812 issue = "87121",
1813 reason = "placeholder syntax for deref patterns"
1814 )]
1815 pub macro deref($pat:pat) {
1816 builtin # deref($pat)
1817 }
1818}
1819