src/libcore/macros.rs

   1 /// Panics the current thread.
   2 ///
   3 /// For details, see `std::macros`.
   4 #[macro_export]
   5 #[allow_internal_unstable(core_panic, __rust_unstable_column)]
   6 #[stable(feature = "core", since = "1.6.0")]
   7 macro_rules! panic {
   8     () => (
   9         $crate::panic!("explicit panic")
  10     );
  11     ($msg:expr) => ({
  12         $crate::panicking::panic(&($msg, file!(), line!(), __rust_unstable_column!()))
  13     });
  14     ($msg:expr,) => (
  15         $crate::panic!($msg)
  16     );
  17     ($fmt:expr, $($arg:tt)+) => ({
  18         $crate::panicking::panic_fmt(format_args!($fmt, $($arg)+),
  19                                      &(file!(), line!(), __rust_unstable_column!()))
  20     });
  21 }
  22
  23 /// Asserts that two expressions are equal to each other (using [`PartialEq`]).
  24 ///
  25 /// On panic, this macro will print the values of the expressions with their
  26 /// debug representations.
  27 ///
  28 /// Like [`assert!`], this macro has a second form, where a custom
  29 /// panic message can be provided.
  30 ///
  31 /// [`PartialEq`]: cmp/trait.PartialEq.html
  32 /// [`assert!`]: macro.assert.html
  33 ///
  34 /// # Examples
  35 ///
  36 /// ```
  37 /// let a = 3;
  38 /// let b = 1 + 2;
  39 /// assert_eq!(a, b);
  40 ///
  41 /// assert_eq!(a, b, "we are testing addition with {} and {}", a, b);
  42 /// ```
  43 #[macro_export]
  44 #[stable(feature = "rust1", since = "1.0.0")]
  45 macro_rules! assert_eq {
  46     ($left:expr, $right:expr) => ({
  47         match (&$left, &$right) {
  48             (left_val, right_val) => {
  49                 if !(*left_val == *right_val) {
  50                     // The reborrows below are intentional. Without them, the stack slot for the
  51                     // borrow is initialized even before the values are compared, leading to a
  52                     // noticeable slow down.
  53                     panic!(r#"assertion failed: `(left == right)`
  54   left: `{:?}`,
  55  right: `{:?}`"#, &*left_val, &*right_val)
  56                 }
  57             }
  58         }
  59     });
  60     ($left:expr, $right:expr,) => ({
  61         $crate::assert_eq!($left, $right)
  62     });
  63     ($left:expr, $right:expr, $($arg:tt)+) => ({
  64         match (&($left), &($right)) {
  65             (left_val, right_val) => {
  66                 if !(*left_val == *right_val) {
  67                     // The reborrows below are intentional. Without them, the stack slot for the
  68                     // borrow is initialized even before the values are compared, leading to a
  69                     // noticeable slow down.
  70                     panic!(r#"assertion failed: `(left == right)`
  71   left: `{:?}`,
  72  right: `{:?}`: {}"#, &*left_val, &*right_val,
  73                            format_args!($($arg)+))
  74                 }
  75             }
  76         }
  77     });
  78 }
  79
  80 /// Asserts that two expressions are not equal to each other (using [`PartialEq`]).
  81 ///
  82 /// On panic, this macro will print the values of the expressions with their
  83 /// debug representations.
  84 ///
  85 /// Like [`assert!`], this macro has a second form, where a custom
  86 /// panic message can be provided.
  87 ///
  88 /// [`PartialEq`]: cmp/trait.PartialEq.html
  89 /// [`assert!`]: macro.assert.html
  90 ///
  91 /// # Examples
  92 ///
  93 /// ```
  94 /// let a = 3;
  95 /// let b = 2;
  96 /// assert_ne!(a, b);
  97 ///
  98 /// assert_ne!(a, b, "we are testing that the values are not equal");
  99 /// ```
 100 #[macro_export]
 101 #[stable(feature = "assert_ne", since = "1.13.0")]
 102 macro_rules! assert_ne {
 103     ($left:expr, $right:expr) => ({
 104         match (&$left, &$right) {
 105             (left_val, right_val) => {
 106                 if *left_val == *right_val {
 107                     // The reborrows below are intentional. Without them, the stack slot for the
 108                     // borrow is initialized even before the values are compared, leading to a
 109                     // noticeable slow down.
 110                     panic!(r#"assertion failed: `(left != right)`
 111   left: `{:?}`,
 112  right: `{:?}`"#, &*left_val, &*right_val)
 113                 }
 114             }
 115         }
 116     });
 117     ($left:expr, $right:expr,) => {
 118         $crate::assert_ne!($left, $right)
 119     };
 120     ($left:expr, $right:expr, $($arg:tt)+) => ({
 121         match (&($left), &($right)) {
 122             (left_val, right_val) => {
 123                 if *left_val == *right_val {
 124                     // The reborrows below are intentional. Without them, the stack slot for the
 125                     // borrow is initialized even before the values are compared, leading to a
 126                     // noticeable slow down.
 127                     panic!(r#"assertion failed: `(left != right)`
 128   left: `{:?}`,
 129  right: `{:?}`: {}"#, &*left_val, &*right_val,
 130                            format_args!($($arg)+))
 131                 }
 132             }
 133         }
 134     });
 135 }
 136
 137 /// Asserts that a boolean expression is `true` at runtime.
 138 ///
 139 /// This will invoke the [`panic!`] macro if the provided expression cannot be
 140 /// evaluated to `true` at runtime.
 141 ///
 142 /// Like [`assert!`], this macro also has a second version, where a custom panic
 143 /// message can be provided.
 144 ///
 145 /// # Uses
 146 ///
 147 /// Unlike [`assert!`], `debug_assert!` statements are only enabled in non
 148 /// optimized builds by default. An optimized build will not execute
 149 /// `debug_assert!` statements unless `-C debug-assertions` is passed to the
 150 /// compiler. This makes `debug_assert!` useful for checks that are too
 151 /// expensive to be present in a release build but may be helpful during
 152 /// development. The result of expanding `debug_assert!` is always type checked.
 153 ///
 154 /// An unchecked assertion allows a program in an inconsistent state to keep
 155 /// running, which might have unexpected consequences but does not introduce
 156 /// unsafety as long as this only happens in safe code. The performance cost
 157 /// of assertions, is however, not measurable in general. Replacing [`assert!`]
 158 /// with `debug_assert!` is thus only encouraged after thorough profiling, and
 159 /// more importantly, only in safe code!
 160 ///
 161 /// [`panic!`]: macro.panic.html
 162 /// [`assert!`]: macro.assert.html
 163 ///
 164 /// # Examples
 165 ///
 166 /// ```
 167 /// // the panic message for these assertions is the stringified value of the
 168 /// // expression given.
 169 /// debug_assert!(true);
 170 ///
 171 /// fn some_expensive_computation() -> bool { true } // a very simple function
 172 /// debug_assert!(some_expensive_computation());
 173 ///
 174 /// // assert with a custom message
 175 /// let x = true;
 176 /// debug_assert!(x, "x wasn't true!");
 177 ///
 178 /// let a = 3; let b = 27;
 179 /// debug_assert!(a + b == 30, "a = {}, b = {}", a, b);
 180 /// ```
 181 #[macro_export]
 182 #[stable(feature = "rust1", since = "1.0.0")]
 183 macro_rules! debug_assert {
 184     ($($arg:tt)*) => (if cfg!(debug_assertions) { assert!($($arg)*); })
 185 }
 186
 187 /// Asserts that two expressions are equal to each other.
 188 ///
 189 /// On panic, this macro will print the values of the expressions with their
 190 /// debug representations.
 191 ///
 192 /// Unlike [`assert_eq!`], `debug_assert_eq!` statements are only enabled in non
 193 /// optimized builds by default. An optimized build will not execute
 194 /// `debug_assert_eq!` statements unless `-C debug-assertions` is passed to the
 195 /// compiler. This makes `debug_assert_eq!` useful for checks that are too
 196 /// expensive to be present in a release build but may be helpful during
 197 /// development. The result of expanding `debug_assert_eq!` is always type checked.
 198 ///
 199 /// [`assert_eq!`]: ../std/macro.assert_eq.html
 200 ///
 201 /// # Examples
 202 ///
 203 /// ```
 204 /// let a = 3;
 205 /// let b = 1 + 2;
 206 /// debug_assert_eq!(a, b);
 207 /// ```
 208 #[macro_export]
 209 #[stable(feature = "rust1", since = "1.0.0")]
 210 macro_rules! debug_assert_eq {
 211     ($($arg:tt)*) => (if cfg!(debug_assertions) { $crate::assert_eq!($($arg)*); })
 212 }
 213
 214 /// Asserts that two expressions are not equal to each other.
 215 ///
 216 /// On panic, this macro will print the values of the expressions with their
 217 /// debug representations.
 218 ///
 219 /// Unlike [`assert_ne!`], `debug_assert_ne!` statements are only enabled in non
 220 /// optimized builds by default. An optimized build will not execute
 221 /// `debug_assert_ne!` statements unless `-C debug-assertions` is passed to the
 222 /// compiler. This makes `debug_assert_ne!` useful for checks that are too
 223 /// expensive to be present in a release build but may be helpful during
 224 /// development. The result of expanding `debug_assert_ne!` is always type checked.
 225 ///
 226 /// [`assert_ne!`]: ../std/macro.assert_ne.html
 227 ///
 228 /// # Examples
 229 ///
 230 /// ```
 231 /// let a = 3;
 232 /// let b = 2;
 233 /// debug_assert_ne!(a, b);
 234 /// ```
 235 #[macro_export]
 236 #[stable(feature = "assert_ne", since = "1.13.0")]
 237 macro_rules! debug_assert_ne {
 238     ($($arg:tt)*) => (if cfg!(debug_assertions) { $crate::assert_ne!($($arg)*); })
 239 }
 240
 241 /// Unwraps a result or propagates its error.
 242 ///
 243 /// The `?` operator was added to replace `try!` and should be used instead.
 244 /// Furthermore, `try` is a reserved word in Rust 2018, so if you must use
 245 /// it, you will need to use the [raw-identifier syntax][ris]: `r#try`.
 246 ///
 247 /// [ris]: https://doc.rust-lang.org/nightly/rust-by-example/compatibility/raw_identifiers.html
 248 ///
 249 /// `try!` matches the given [`Result`]. In case of the `Ok` variant, the
 250 /// expression has the value of the wrapped value.
 251 ///
 252 /// In case of the `Err` variant, it retrieves the inner error. `try!` then
 253 /// performs conversion using `From`. This provides automatic conversion
 254 /// between specialized errors and more general ones. The resulting
 255 /// error is then immediately returned.
 256 ///
 257 /// Because of the early return, `try!` can only be used in functions that
 258 /// return [`Result`].
 259 ///
 260 /// [`Result`]: ../std/result/enum.Result.html
 261 ///
 262 /// # Examples
 263 ///
 264 /// ```
 265 /// use std::io;
 266 /// use std::fs::File;
 267 /// use std::io::prelude::*;
 268 ///
 269 /// enum MyError {
 270 ///     FileWriteError
 271 /// }
 272 ///
 273 /// impl From<io::Error> for MyError {
 274 ///     fn from(e: io::Error) -> MyError {
 275 ///         MyError::FileWriteError
 276 ///     }
 277 /// }
 278 ///
 279 /// // The preferred method of quick returning Errors
 280 /// fn write_to_file_question() -> Result<(), MyError> {
 281 ///     let mut file = File::create("my_best_friends.txt")?;
 282 ///     file.write_all(b"This is a list of my best friends.")?;
 283 ///     Ok(())
 284 /// }
 285 ///
 286 /// // The previous method of quick returning Errors
 287 /// fn write_to_file_using_try() -> Result<(), MyError> {
 288 ///     let mut file = r#try!(File::create("my_best_friends.txt"));
 289 ///     r#try!(file.write_all(b"This is a list of my best friends."));
 290 ///     Ok(())
 291 /// }
 292 ///
 293 /// // This is equivalent to:
 294 /// fn write_to_file_using_match() -> Result<(), MyError> {
 295 ///     let mut file = r#try!(File::create("my_best_friends.txt"));
 296 ///     match file.write_all(b"This is a list of my best friends.") {
 297 ///         Ok(v) => v,
 298 ///         Err(e) => return Err(From::from(e)),
 299 ///     }
 300 ///     Ok(())
 301 /// }
 302 /// ```
 303 #[macro_export]
 304 #[stable(feature = "rust1", since = "1.0.0")]
 305 #[doc(alias = "?")]
 306 macro_rules! r#try {
 307     ($expr:expr) => (match $expr {
 308         $crate::result::Result::Ok(val) => val,
 309         $crate::result::Result::Err(err) => {
 310             return $crate::result::Result::Err($crate::convert::From::from(err))
 311         }
 312     });
 313     ($expr:expr,) => ($crate::r#try!($expr));
 314 }
 315
 316 /// Writes formatted data into a buffer.
 317 ///
 318 /// This macro accepts a format string, a list of arguments, and a 'writer'. Arguments will be
 319 /// formatted according to the specified format string and the result will be passed to the writer.
 320 /// The writer may be any value with a `write_fmt` method; generally this comes from an
 321 /// implementation of either the [`std::fmt::Write`] or the [`std::io::Write`] trait. The macro
 322 /// returns whatever the `write_fmt` method returns; commonly a [`std::fmt::Result`], or an
 323 /// [`io::Result`].
 324 ///
 325 /// See [`std::fmt`] for more information on the format string syntax.
 326 ///
 327 /// [`std::fmt`]: ../std/fmt/index.html
 328 /// [`std::fmt::Write`]: ../std/fmt/trait.Write.html
 329 /// [`std::io::Write`]: ../std/io/trait.Write.html
 330 /// [`std::fmt::Result`]: ../std/fmt/type.Result.html
 331 /// [`io::Result`]: ../std/io/type.Result.html
 332 ///
 333 /// # Examples
 334 ///
 335 /// ```
 336 /// use std::io::Write;
 337 ///
 338 /// fn main() -> std::io::Result<()> {
 339 ///     let mut w = Vec::new();
 340 ///     write!(&mut w, "test")?;
 341 ///     write!(&mut w, "formatted {}", "arguments")?;
 342 ///
 343 ///     assert_eq!(w, b"testformatted arguments");
 344 ///     Ok(())
 345 /// }
 346 /// ```
 347 ///
 348 /// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
 349 /// implementing either, as objects do not typically implement both. However, the module must
 350 /// import the traits qualified so their names do not conflict:
 351 ///
 352 /// ```
 353 /// use std::fmt::Write as FmtWrite;
 354 /// use std::io::Write as IoWrite;
 355 ///
 356 /// fn main() -> Result<(), Box<dyn std::error::Error>> {
 357 ///     let mut s = String::new();
 358 ///     let mut v = Vec::new();
 359 ///
 360 ///     write!(&mut s, "{} {}", "abc", 123)?; // uses fmt::Write::write_fmt
 361 ///     write!(&mut v, "s = {:?}", s)?; // uses io::Write::write_fmt
 362 ///     assert_eq!(v, b"s = \"abc 123\"");
 363 ///     Ok(())
 364 /// }
 365 /// ```
 366 ///
 367 /// Note: This macro can be used in `no_std` setups as well.
 368 /// In a `no_std` setup you are responsible for the implementation details of the components.
 369 ///
 370 /// ```no_run
 371 /// # extern crate core;
 372 /// use core::fmt::Write;
 373 ///
 374 /// struct Example;
 375 ///
 376 /// impl Write for Example {
 377 ///     fn write_str(&mut self, _s: &str) -> core::fmt::Result {
 378 ///          unimplemented!();
 379 ///     }
 380 /// }
 381 ///
 382 /// let mut m = Example{};
 383 /// write!(&mut m, "Hello World").expect("Not written");
 384 /// ```
 385 #[macro_export]
 386 #[stable(feature = "rust1", since = "1.0.0")]
 387 macro_rules! write {
 388     ($dst:expr, $($arg:tt)*) => ($dst.write_fmt(format_args!($($arg)*)))
 389 }
 390
 391 /// Write formatted data into a buffer, with a newline appended.
 392 ///
 393 /// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
 394 /// (no additional CARRIAGE RETURN (`\r`/`U+000D`).
 395 ///
 396 /// For more information, see [`write!`]. For information on the format string syntax, see
 397 /// [`std::fmt`].
 398 ///
 399 /// [`write!`]: macro.write.html
 400 /// [`std::fmt`]: ../std/fmt/index.html
 401 ///
 402 ///
 403 /// # Examples
 404 ///
 405 /// ```
 406 /// use std::io::{Write, Result};
 407 ///
 408 /// fn main() -> Result<()> {
 409 ///     let mut w = Vec::new();
 410 ///     writeln!(&mut w)?;
 411 ///     writeln!(&mut w, "test")?;
 412 ///     writeln!(&mut w, "formatted {}", "arguments")?;
 413 ///
 414 ///     assert_eq!(&w[..], "\ntest\nformatted arguments\n".as_bytes());
 415 ///     Ok(())
 416 /// }
 417 /// ```
 418 ///
 419 /// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
 420 /// implementing either, as objects do not typically implement both. However, the module must
 421 /// import the traits qualified so their names do not conflict:
 422 ///
 423 /// ```
 424 /// use std::fmt::Write as FmtWrite;
 425 /// use std::io::Write as IoWrite;
 426 ///
 427 /// fn main() -> Result<(), Box<dyn std::error::Error>> {
 428 ///     let mut s = String::new();
 429 ///     let mut v = Vec::new();
 430 ///
 431 ///     writeln!(&mut s, "{} {}", "abc", 123)?; // uses fmt::Write::write_fmt
 432 ///     writeln!(&mut v, "s = {:?}", s)?; // uses io::Write::write_fmt
 433 ///     assert_eq!(v, b"s = \"abc 123\\n\"\n");
 434 ///     Ok(())
 435 /// }
 436 /// ```
 437 #[macro_export]
 438 #[stable(feature = "rust1", since = "1.0.0")]
 439 #[allow_internal_unstable(format_args_nl)]
 440 macro_rules! writeln {
 441     ($dst:expr) => (
 442         $crate::write!($dst, "\n")
 443     );
 444     ($dst:expr,) => (
 445         $crate::writeln!($dst)
 446     );
 447     ($dst:expr, $($arg:tt)*) => (
 448         $dst.write_fmt(format_args_nl!($($arg)*))
 449     );
 450 }
 451
 452 /// Indicates unreachable code.
 453 ///
 454 /// This is useful any time that the compiler can't determine that some code is unreachable. For
 455 /// example:
 456 ///
 457 /// * Match arms with guard conditions.
 458 /// * Loops that dynamically terminate.
 459 /// * Iterators that dynamically terminate.
 460 ///
 461 /// If the determination that the code is unreachable proves incorrect, the
 462 /// program immediately terminates with a [`panic!`].
 463 ///
 464 /// The unsafe counterpart of this macro is the [`unreachable_unchecked`] function, which
 465 /// will cause undefined behavior if the code is reached.
 466 ///
 467 /// [`panic!`]:  ../std/macro.panic.html
 468 /// [`unreachable_unchecked`]: ../std/hint/fn.unreachable_unchecked.html
 469 /// [`std::hint`]: ../std/hint/index.html
 470 ///
 471 /// # Panics
 472 ///
 473 /// This will always [`panic!`]
 474 ///
 475 /// [`panic!`]: ../std/macro.panic.html
 476 /// # Examples
 477 ///
 478 /// Match arms:
 479 ///
 480 /// ```
 481 /// # #[allow(dead_code)]
 482 /// fn foo(x: Option<i32>) {
 483 ///     match x {
 484 ///         Some(n) if n >= 0 => println!("Some(Non-negative)"),
 485 ///         Some(n) if n <  0 => println!("Some(Negative)"),
 486 ///         Some(_)           => unreachable!(), // compile error if commented out
 487 ///         None              => println!("None")
 488 ///     }
 489 /// }
 490 /// ```
 491 ///
 492 /// Iterators:
 493 ///
 494 /// ```
 495 /// # #[allow(dead_code)]
 496 /// fn divide_by_three(x: u32) -> u32 { // one of the poorest implementations of x/3
 497 ///     for i in 0.. {
 498 ///         if 3*i < i { panic!("u32 overflow"); }
 499 ///         if x < 3*i { return i-1; }
 500 ///     }
 501 ///     unreachable!();
 502 /// }
 503 /// ```
 504 #[macro_export]
 505 #[stable(feature = "rust1", since = "1.0.0")]
 506 macro_rules! unreachable {
 507     () => ({
 508         panic!("internal error: entered unreachable code")
 509     });
 510     ($msg:expr) => ({
 511         $crate::unreachable!("{}", $msg)
 512     });
 513     ($msg:expr,) => ({
 514         $crate::unreachable!($msg)
 515     });
 516     ($fmt:expr, $($arg:tt)*) => ({
 517         panic!(concat!("internal error: entered unreachable code: ", $fmt), $($arg)*)
 518     });
 519 }
 520
 521 /// Indicates unfinished code.
 522 ///
 523 /// This can be useful if you are prototyping and are just looking to have your
 524 /// code type-check, or if you're implementing a trait that requires multiple
 525 /// methods, and you're only planning on using one of them.
 526 ///
 527 /// # Panics
 528 ///
 529 /// This will always [panic!](macro.panic.html)
 530 ///
 531 /// # Examples
 532 ///
 533 /// Here's an example of some in-progress code. We have a trait `Foo`:
 534 ///
 535 /// ```
 536 /// trait Foo {
 537 ///     fn bar(&self);
 538 ///     fn baz(&self);
 539 /// }
 540 /// ```
 541 ///
 542 /// We want to implement `Foo` on one of our types, but we also want to work on
 543 /// just `bar()` first. In order for our code to compile, we need to implement
 544 /// `baz()`, so we can use `unimplemented!`:
 545 ///
 546 /// ```
 547 /// # trait Foo {
 548 /// #     fn bar(&self);
 549 /// #     fn baz(&self);
 550 /// # }
 551 /// struct MyStruct;
 552 ///
 553 /// impl Foo for MyStruct {
 554 ///     fn bar(&self) {
 555 ///         // implementation goes here
 556 ///     }
 557 ///
 558 ///     fn baz(&self) {
 559 ///         // let's not worry about implementing baz() for now
 560 ///         unimplemented!();
 561 ///     }
 562 /// }
 563 ///
 564 /// fn main() {
 565 ///     let s = MyStruct;
 566 ///     s.bar();
 567 ///
 568 ///     // we aren't even using baz() yet, so this is fine.
 569 /// }
 570 /// ```
 571 #[macro_export]
 572 #[stable(feature = "rust1", since = "1.0.0")]
 573 macro_rules! unimplemented {
 574     () => (panic!("not yet implemented"));
 575     ($($arg:tt)+) => (panic!("not yet implemented: {}", format_args!($($arg)+)));
 576 }
 577
 578 /// Indicates unfinished code.
 579 ///
 580 /// This can be useful if you are prototyping and are just looking to have your
 581 /// code typecheck. `todo!` works exactly like `unimplemented!`. The only
 582 /// difference between the two macros is the name.
 583 ///
 584 /// # Panics
 585 ///
 586 /// This will always [panic!](macro.panic.html)
 587 ///
 588 /// # Examples
 589 ///
 590 /// Here's an example of some in-progress code. We have a trait `Foo`:
 591 ///
 592 /// ```
 593 /// trait Foo {
 594 ///     fn bar(&self);
 595 ///     fn baz(&self);
 596 /// }
 597 /// ```
 598 ///
 599 /// We want to implement `Foo` on one of our types, but we also want to work on
 600 /// just `bar()` first. In order for our code to compile, we need to implement
 601 /// `baz()`, so we can use `todo!`:
 602 ///
 603 /// ```
 604 /// #![feature(todo_macro)]
 605 ///
 606 /// # trait Foo {
 607 /// #     fn bar(&self);
 608 /// #     fn baz(&self);
 609 /// # }
 610 /// struct MyStruct;
 611 ///
 612 /// impl Foo for MyStruct {
 613 ///     fn bar(&self) {
 614 ///         // implementation goes here
 615 ///     }
 616 ///
 617 ///     fn baz(&self) {
 618 ///         // let's not worry about implementing baz() for now
 619 ///         todo!();
 620 ///     }
 621 /// }
 622 ///
 623 /// fn main() {
 624 ///     let s = MyStruct;
 625 ///     s.bar();
 626 ///
 627 ///     // we aren't even using baz() yet, so this is fine.
 628 /// }
 629 /// ```
 630 #[macro_export]
 631 #[unstable(feature = "todo_macro", issue = "59277")]
 632 macro_rules! todo {
 633     () => (panic!("not yet implemented"));
 634     ($($arg:tt)+) => (panic!("not yet implemented: {}", format_args!($($arg)+)));
 635 }
 636
 637 /// Creates an array of [`MaybeUninit`].
 638 ///
 639 /// This macro constructs an uninitialized array of the type `[MaybeUninit<K>; N]`.
 640 /// It exists solely because bootstrap does not yet support const array-init expressions.
 641 ///
 642 /// [`MaybeUninit`]: mem/union.MaybeUninit.html
 643 // FIXME: Remove both versions of this macro once bootstrap is 1.38.
 644 #[macro_export]
 645 #[unstable(feature = "maybe_uninit_array", issue = "53491")]
 646 #[cfg(bootstrap)]
 647 macro_rules! uninit_array {
 648     // This `assume_init` is safe because an array of `MaybeUninit` does not
 649     // require initialization.
 650     ($t:ty; $size:expr) => (unsafe {
 651         MaybeUninit::<[MaybeUninit<$t>; $size]>::uninit().assume_init()
 652     });
 653 }
 654
 655 /// Creates an array of [`MaybeUninit`].
 656 ///
 657 /// This macro constructs an uninitialized array of the type `[MaybeUninit<K>; N]`.
 658 /// It exists solely because bootstrap does not yet support const array-init expressions.
 659 ///
 660 /// [`MaybeUninit`]: mem/union.MaybeUninit.html
 661 // FIXME: Just inline this version of the macro once bootstrap is 1.38.
 662 #[macro_export]
 663 #[unstable(feature = "maybe_uninit_array", issue = "53491")]
 664 #[cfg(not(bootstrap))]
 665 macro_rules! uninit_array {
 666     ($t:ty; $size:expr) => (
 667         [MaybeUninit::<$t>::UNINIT; $size]
 668     );
 669 }
 670
 671 /// Definitions of built-in macros.
 672 ///
 673 /// Most of the macro properties (stability, visibility, etc.) are taken from the source code here,
 674 /// with exception of expansion functions transforming macro inputs into outputs,
 675 /// those functions are provided by the compiler.
 676 #[cfg(not(bootstrap))]
 677 pub(crate) mod builtin {
 678
 679     /// Causes compilation to fail with the given error message when encountered.
 680     ///
 681     /// This macro should be used when a crate uses a conditional compilation strategy to provide
 682     /// better error messages for erroneous conditions. It's the compiler-level form of [`panic!`],
 683     /// which emits an error at *runtime*, rather than during compilation.
 684     ///
 685     /// # Examples
 686     ///
 687     /// Two such examples are macros and `#[cfg]` environments.
 688     ///
 689     /// Emit better compiler error if a macro is passed invalid values. Without the final branch,
 690     /// the compiler would still emit an error, but the error's message would not mention the two
 691     /// valid values.
 692     ///
 693     /// ```compile_fail
 694     /// macro_rules! give_me_foo_or_bar {
 695     ///     (foo) => {};
 696     ///     (bar) => {};
 697     ///     ($x:ident) => {
 698     ///         compile_error!("This macro only accepts `foo` or `bar`");
 699     ///     }
 700     /// }
 701     ///
 702     /// give_me_foo_or_bar!(neither);
 703     /// // ^ will fail at compile time with message "This macro only accepts `foo` or `bar`"
 704     /// ```
 705     ///
 706     /// Emit compiler error if one of a number of features isn't available.
 707     ///
 708     /// ```compile_fail
 709     /// #[cfg(not(any(feature = "foo", feature = "bar")))]
 710     /// compile_error!("Either feature \"foo\" or \"bar\" must be enabled for this crate.");
 711     /// ```
 712     ///
 713     /// [`panic!`]: ../std/macro.panic.html
 714     #[stable(feature = "compile_error_macro", since = "1.20.0")]
 715     #[rustc_builtin_macro]
 716     #[rustc_macro_transparency = "semitransparent"]
 717     pub macro compile_error {
 718         ($msg:expr) => ({ /* compiler built-in */ }),
 719         ($msg:expr,) => ({ /* compiler built-in */ })
 720     }
 721
 722     /// Constructs parameters for the other string-formatting macros.
 723     ///
 724     /// This macro functions by taking a formatting string literal containing
 725     /// `{}` for each additional argument passed. `format_args!` prepares the
 726     /// additional parameters to ensure the output can be interpreted as a string
 727     /// and canonicalizes the arguments into a single type. Any value that implements
 728     /// the [`Display`] trait can be passed to `format_args!`, as can any
 729     /// [`Debug`] implementation be passed to a `{:?}` within the formatting string.
 730     ///
 731     /// This macro produces a value of type [`fmt::Arguments`]. This value can be
 732     /// passed to the macros within [`std::fmt`] for performing useful redirection.
 733     /// All other formatting macros ([`format!`], [`write!`], [`println!`], etc) are
 734     /// proxied through this one. `format_args!`, unlike its derived macros, avoids
 735     /// heap allocations.
 736     ///
 737     /// You can use the [`fmt::Arguments`] value that `format_args!` returns
 738     /// in `Debug` and `Display` contexts as seen below. The example also shows
 739     /// that `Debug` and `Display` format to the same thing: the interpolated
 740     /// format string in `format_args!`.
 741     ///
 742     /// ```rust
 743     /// let debug = format!("{:?}", format_args!("{} foo {:?}", 1, 2));
 744     /// let display = format!("{}", format_args!("{} foo {:?}", 1, 2));
 745     /// assert_eq!("1 foo 2", display);
 746     /// assert_eq!(display, debug);
 747     /// ```
 748     ///
 749     /// For more information, see the documentation in [`std::fmt`].
 750     ///
 751     /// [`Display`]: ../std/fmt/trait.Display.html
 752     /// [`Debug`]: ../std/fmt/trait.Debug.html
 753     /// [`fmt::Arguments`]: ../std/fmt/struct.Arguments.html
 754     /// [`std::fmt`]: ../std/fmt/index.html
 755     /// [`format!`]: ../std/macro.format.html
 756     /// [`write!`]: ../std/macro.write.html
 757     /// [`println!`]: ../std/macro.println.html
 758     ///
 759     /// # Examples
 760     ///
 761     /// ```
 762     /// use std::fmt;
 763     ///
 764     /// let s = fmt::format(format_args!("hello {}", "world"));
 765     /// assert_eq!(s, format!("hello {}", "world"));
 766     /// ```
 767     #[stable(feature = "rust1", since = "1.0.0")]
 768     #[allow_internal_unstable(fmt_internals)]
 769     #[rustc_builtin_macro]
 770     #[rustc_macro_transparency = "semitransparent"]
 771     pub macro format_args {
 772         ($fmt:expr) => ({ /* compiler built-in */ }),
 773         ($fmt:expr, $($args:tt)*) => ({ /* compiler built-in */ })
 774     }
 775
 776     /// Same as `format_args`, but adds a newline in the end.
 777     #[unstable(feature = "format_args_nl", issue = "0",
 778                reason = "`format_args_nl` is only for internal \
 779                          language use and is subject to change")]
 780     #[allow_internal_unstable(fmt_internals)]
 781     #[rustc_builtin_macro]
 782     #[rustc_macro_transparency = "semitransparent"]
 783     pub macro format_args_nl {
 784         ($fmt:expr) => ({ /* compiler built-in */ }),
 785         ($fmt:expr, $($args:tt)*) => ({ /* compiler built-in */ })
 786     }
 787
 788     /// Inspects an environment variable at compile time.
 789     ///
 790     /// This macro will expand to the value of the named environment variable at
 791     /// compile time, yielding an expression of type `&'static str`.
 792     ///
 793     /// If the environment variable is not defined, then a compilation error
 794     /// will be emitted. To not emit a compile error, use the [`option_env!`]
 795     /// macro instead.
 796     ///
 797     /// [`option_env!`]: ../std/macro.option_env.html
 798     ///
 799     /// # Examples
 800     ///
 801     /// ```
 802     /// let path: &'static str = env!("PATH");
 803     /// println!("the $PATH variable at the time of compiling was: {}", path);
 804     /// ```
 805     ///
 806     /// You can customize the error message by passing a string as the second
 807     /// parameter:
 808     ///
 809     /// ```compile_fail
 810     /// let doc: &'static str = env!("documentation", "what's that?!");
 811     /// ```
 812     ///
 813     /// If the `documentation` environment variable is not defined, you'll get
 814     /// the following error:
 815     ///
 816     /// ```text
 817     /// error: what's that?!
 818     /// ```
 819     #[stable(feature = "rust1", since = "1.0.0")]
 820     #[rustc_builtin_macro]
 821     #[rustc_macro_transparency = "semitransparent"]
 822     pub macro env {
 823         ($name:expr) => ({ /* compiler built-in */ }),
 824         ($name:expr,) => ({ /* compiler built-in */ })
 825     }
 826
 827     /// Optionally inspects an environment variable at compile time.
 828     ///
 829     /// If the named environment variable is present at compile time, this will
 830     /// expand into an expression of type `Option<&'static str>` whose value is
 831     /// `Some` of the value of the environment variable. If the environment
 832     /// variable is not present, then this will expand to `None`. See
 833     /// [`Option<T>`][option] for more information on this type.
 834     ///
 835     /// A compile time error is never emitted when using this macro regardless
 836     /// of whether the environment variable is present or not.
 837     ///
 838     /// [option]: ../std/option/enum.Option.html
 839     ///
 840     /// # Examples
 841     ///
 842     /// ```
 843     /// let key: Option<&'static str> = option_env!("SECRET_KEY");
 844     /// println!("the secret key might be: {:?}", key);
 845     /// ```
 846     #[stable(feature = "rust1", since = "1.0.0")]
 847     #[rustc_builtin_macro]
 848     #[rustc_macro_transparency = "semitransparent"]
 849     pub macro option_env {
 850         ($name:expr) => ({ /* compiler built-in */ }),
 851         ($name:expr,) => ({ /* compiler built-in */ })
 852     }
 853
 854     /// Concatenates identifiers into one identifier.
 855     ///
 856     /// This macro takes any number of comma-separated identifiers, and
 857     /// concatenates them all into one, yielding an expression which is a new
 858     /// identifier. Note that hygiene makes it such that this macro cannot
 859     /// capture local variables. Also, as a general rule, macros are only
 860     /// allowed in item, statement or expression position. That means while
 861     /// you may use this macro for referring to existing variables, functions or
 862     /// modules etc, you cannot define a new one with it.
 863     ///
 864     /// # Examples
 865     ///
 866     /// ```
 867     /// #![feature(concat_idents)]
 868     ///
 869     /// # fn main() {
 870     /// fn foobar() -> u32 { 23 }
 871     ///
 872     /// let f = concat_idents!(foo, bar);
 873     /// println!("{}", f());
 874     ///
 875     /// // fn concat_idents!(new, fun, name) { } // not usable in this way!
 876     /// # }
 877     /// ```
 878     #[unstable(feature = "concat_idents", issue = "29599",
 879                reason = "`concat_idents` is not stable enough for use and is subject to change")]
 880     #[rustc_builtin_macro]
 881     #[rustc_macro_transparency = "semitransparent"]
 882     pub macro concat_idents {
 883         ($($e:ident),+) => ({ /* compiler built-in */ }),
 884         ($($e:ident,)+) => ({ /* compiler built-in */ })
 885     }
 886
 887     /// Concatenates literals into a static string slice.
 888     ///
 889     /// This macro takes any number of comma-separated literals, yielding an
 890     /// expression of type `&'static str` which represents all of the literals
 891     /// concatenated left-to-right.
 892     ///
 893     /// Integer and floating point literals are stringified in order to be
 894     /// concatenated.
 895     ///
 896     /// # Examples
 897     ///
 898     /// ```
 899     /// let s = concat!("test", 10, 'b', true);
 900     /// assert_eq!(s, "test10btrue");
 901     /// ```
 902     #[stable(feature = "rust1", since = "1.0.0")]
 903     #[rustc_builtin_macro]
 904     #[rustc_macro_transparency = "semitransparent"]
 905     pub macro concat {
 906         ($($e:expr),*) => ({ /* compiler built-in */ }),
 907         ($($e:expr,)*) => ({ /* compiler built-in */ })
 908     }
 909
 910     /// Expands to the line number on which it was invoked.
 911     ///
 912     /// With [`column!`] and [`file!`], these macros provide debugging information for
 913     /// developers about the location within the source.
 914     ///
 915     /// The expanded expression has type `u32` and is 1-based, so the first line
 916     /// in each file evaluates to 1, the second to 2, etc. This is consistent
 917     /// with error messages by common compilers or popular editors.
 918     /// The returned line is *not necessarily* the line of the `line!` invocation itself,
 919     /// but rather the first macro invocation leading up to the invocation
 920     /// of the `line!` macro.
 921     ///
 922     /// [`column!`]: macro.column.html
 923     /// [`file!`]: macro.file.html
 924     ///
 925     /// # Examples
 926     ///
 927     /// ```
 928     /// let current_line = line!();
 929     /// println!("defined on line: {}", current_line);
 930     /// ```
 931     #[stable(feature = "rust1", since = "1.0.0")]
 932     #[rustc_builtin_macro]
 933     #[rustc_macro_transparency = "semitransparent"]
 934     pub macro line() { /* compiler built-in */ }
 935
 936     /// Expands to the column number at which it was invoked.
 937     ///
 938     /// With [`line!`] and [`file!`], these macros provide debugging information for
 939     /// developers about the location within the source.
 940     ///
 941     /// The expanded expression has type `u32` and is 1-based, so the first column
 942     /// in each line evaluates to 1, the second to 2, etc. This is consistent
 943     /// with error messages by common compilers or popular editors.
 944     /// The returned column is *not necessarily* the line of the `column!` invocation itself,
 945     /// but rather the first macro invocation leading up to the invocation
 946     /// of the `column!` macro.
 947     ///
 948     /// [`line!`]: macro.line.html
 949     /// [`file!`]: macro.file.html
 950     ///
 951     /// # Examples
 952     ///
 953     /// ```
 954     /// let current_col = column!();
 955     /// println!("defined on column: {}", current_col);
 956     /// ```
 957     #[stable(feature = "rust1", since = "1.0.0")]
 958     #[rustc_builtin_macro]
 959     #[rustc_macro_transparency = "semitransparent"]
 960     pub macro column() { /* compiler built-in */ }
 961
 962     /// Same as `column`, but less likely to be shadowed.
 963     #[unstable(feature = "__rust_unstable_column", issue = "0",
 964                reason = "internal implementation detail of the `panic` macro")]
 965     #[rustc_builtin_macro]
 966     #[rustc_macro_transparency = "semitransparent"]
 967     pub macro __rust_unstable_column() { /* compiler built-in */ }
 968
 969     /// Expands to the file name in which it was invoked.
 970     ///
 971     /// With [`line!`] and [`column!`], these macros provide debugging information for
 972     /// developers about the location within the source.
 973     ///
 974     ///
 975     /// The expanded expression has type `&'static str`, and the returned file
 976     /// is not the invocation of the `file!` macro itself, but rather the
 977     /// first macro invocation leading up to the invocation of the `file!`
 978     /// macro.
 979     ///
 980     /// [`line!`]: macro.line.html
 981     /// [`column!`]: macro.column.html
 982     ///
 983     /// # Examples
 984     ///
 985     /// ```
 986     /// let this_file = file!();
 987     /// println!("defined in file: {}", this_file);
 988     /// ```
 989     #[stable(feature = "rust1", since = "1.0.0")]
 990     #[rustc_builtin_macro]
 991     #[rustc_macro_transparency = "semitransparent"]
 992     pub macro file() { /* compiler built-in */ }
 993
 994     /// Stringifies its arguments.
 995     ///
 996     /// This macro will yield an expression of type `&'static str` which is the
 997     /// stringification of all the tokens passed to the macro. No restrictions
 998     /// are placed on the syntax of the macro invocation itself.
 999     ///
1000     /// Note that the expanded results of the input tokens may change in the
1001     /// future. You should be careful if you rely on the output.
1002     ///
1003     /// # Examples
1004     ///
1005     /// ```
1006     /// let one_plus_one = stringify!(1 + 1);
1007     /// assert_eq!(one_plus_one, "1 + 1");
1008     /// ```
1009     #[stable(feature = "rust1", since = "1.0.0")]
1010     #[rustc_builtin_macro]
1011     #[rustc_macro_transparency = "semitransparent"]
1012     pub macro stringify($($t:tt)*) { /* compiler built-in */ }
1013
1014     /// Includes a utf8-encoded file as a string.
1015     ///
1016     /// The file is located relative to the current file. (similarly to how
1017     /// modules are found)
1018     ///
1019     /// This macro will yield an expression of type `&'static str` which is the
1020     /// contents of the file.
1021     ///
1022     /// # Examples
1023     ///
1024     /// Assume there are two files in the same directory with the following
1025     /// contents:
1026     ///
1027     /// File 'spanish.in':
1028     ///
1029     /// ```text
1030     /// adiós
1031     /// ```
1032     ///
1033     /// File 'main.rs':
1034     ///
1035     /// ```ignore (cannot-doctest-external-file-dependency)
1036     /// fn main() {
1037     ///     let my_str = include_str!("spanish.in");
1038     ///     assert_eq!(my_str, "adiós\n");
1039     ///     print!("{}", my_str);
1040     /// }
1041     /// ```
1042     ///
1043     /// Compiling 'main.rs' and running the resulting binary will print "adiós".
1044     #[stable(feature = "rust1", since = "1.0.0")]
1045     #[rustc_builtin_macro]
1046     #[rustc_macro_transparency = "semitransparent"]
1047     pub macro include_str {
1048         ($file:expr) => ({ /* compiler built-in */ }),
1049         ($file:expr,) => ({ /* compiler built-in */ })
1050     }
1051
1052     /// Includes a file as a reference to a byte array.
1053     ///
1054     /// The file is located relative to the current file. (similarly to how
1055     /// modules are found)
1056     ///
1057     /// This macro will yield an expression of type `&'static [u8; N]` which is
1058     /// the contents of the file.
1059     ///
1060     /// # Examples
1061     ///
1062     /// Assume there are two files in the same directory with the following
1063     /// contents:
1064     ///
1065     /// File 'spanish.in':
1066     ///
1067     /// ```text
1068     /// adiós
1069     /// ```
1070     ///
1071     /// File 'main.rs':
1072     ///
1073     /// ```ignore (cannot-doctest-external-file-dependency)
1074     /// fn main() {
1075     ///     let bytes = include_bytes!("spanish.in");
1076     ///     assert_eq!(bytes, b"adi\xc3\xb3s\n");
1077     ///     print!("{}", String::from_utf8_lossy(bytes));
1078     /// }
1079     /// ```
1080     ///
1081     /// Compiling 'main.rs' and running the resulting binary will print "adiós".
1082     #[stable(feature = "rust1", since = "1.0.0")]
1083     #[rustc_builtin_macro]
1084     #[rustc_macro_transparency = "semitransparent"]
1085     pub macro include_bytes {
1086         ($file:expr) => ({ /* compiler built-in */ }),
1087         ($file:expr,) => ({ /* compiler built-in */ })
1088     }
1089
1090     /// Expands to a string that represents the current module path.
1091     ///
1092     /// The current module path can be thought of as the hierarchy of modules
1093     /// leading back up to the crate root. The first component of the path
1094     /// returned is the name of the crate currently being compiled.
1095     ///
1096     /// # Examples
1097     ///
1098     /// ```
1099     /// mod test {
1100     ///     pub fn foo() {
1101     ///         assert!(module_path!().ends_with("test"));
1102     ///     }
1103     /// }
1104     ///
1105     /// test::foo();
1106     /// ```
1107     #[stable(feature = "rust1", since = "1.0.0")]
1108     #[rustc_builtin_macro]
1109     #[rustc_macro_transparency = "semitransparent"]
1110     pub macro module_path() { /* compiler built-in */ }
1111
1112     /// Evaluates boolean combinations of configuration flags at compile-time.
1113     ///
1114     /// In addition to the `#[cfg]` attribute, this macro is provided to allow
1115     /// boolean expression evaluation of configuration flags. This frequently
1116     /// leads to less duplicated code.
1117     ///
1118     /// The syntax given to this macro is the same syntax as the [`cfg`]
1119     /// attribute.
1120     ///
1121     /// [`cfg`]: ../reference/conditional-compilation.html#the-cfg-attribute
1122     ///
1123     /// # Examples
1124     ///
1125     /// ```
1126     /// let my_directory = if cfg!(windows) {
1127     ///     "windows-specific-directory"
1128     /// } else {
1129     ///     "unix-directory"
1130     /// };
1131     /// ```
1132     #[stable(feature = "rust1", since = "1.0.0")]
1133     #[rustc_builtin_macro]
1134     #[rustc_macro_transparency = "semitransparent"]
1135     pub macro cfg($($cfg:tt)*) { /* compiler built-in */ }
1136
1137     /// Parses a file as an expression or an item according to the context.
1138     ///
1139     /// The file is located relative to the current file (similarly to how
1140     /// modules are found).
1141     ///
1142     /// Using this macro is often a bad idea, because if the file is
1143     /// parsed as an expression, it is going to be placed in the
1144     /// surrounding code unhygienically. This could result in variables
1145     /// or functions being different from what the file expected if
1146     /// there are variables or functions that have the same name in
1147     /// the current file.
1148     ///
1149     /// # Examples
1150     ///
1151     /// Assume there are two files in the same directory with the following
1152     /// contents:
1153     ///
1154     /// File 'monkeys.in':
1155     ///
1156     /// ```ignore (only-for-syntax-highlight)
1157     /// ['🙈', '🙊', '🙉']
1158     ///     .iter()
1159     ///     .cycle()
1160     ///     .take(6)
1161     ///     .collect::<String>()
1162     /// ```
1163     ///
1164     /// File 'main.rs':
1165     ///
1166     /// ```ignore (cannot-doctest-external-file-dependency)
1167     /// fn main() {
1168     ///     let my_string = include!("monkeys.in");
1169     ///     assert_eq!("🙈🙊🙉🙈🙊🙉", my_string);
1170     ///     println!("{}", my_string);
1171     /// }
1172     /// ```
1173     ///
1174     /// Compiling 'main.rs' and running the resulting binary will print
1175     /// "🙈🙊🙉🙈🙊🙉".
1176     #[stable(feature = "rust1", since = "1.0.0")]
1177     #[rustc_builtin_macro]
1178     #[rustc_macro_transparency = "semitransparent"]
1179     pub macro include {
1180         ($file:expr) => ({ /* compiler built-in */ }),
1181         ($file:expr,) => ({ /* compiler built-in */ })
1182     }
1183
1184     /// Asserts that a boolean expression is `true` at runtime.
1185     ///
1186     /// This will invoke the [`panic!`] macro if the provided expression cannot be
1187     /// evaluated to `true` at runtime.
1188     ///
1189     /// # Uses
1190     ///
1191     /// Assertions are always checked in both debug and release builds, and cannot
1192     /// be disabled. See [`debug_assert!`] for assertions that are not enabled in
1193     /// release builds by default.
1194     ///
1195     /// Unsafe code relies on `assert!` to enforce run-time invariants that, if
1196     /// violated could lead to unsafety.
1197     ///
1198     /// Other use-cases of `assert!` include testing and enforcing run-time
1199     /// invariants in safe code (whose violation cannot result in unsafety).
1200     ///
1201     /// # Custom Messages
1202     ///
1203     /// This macro has a second form, where a custom panic message can
1204     /// be provided with or without arguments for formatting. See [`std::fmt`]
1205     /// for syntax for this form.
1206     ///
1207     /// [`panic!`]: macro.panic.html
1208     /// [`debug_assert!`]: macro.debug_assert.html
1209     /// [`std::fmt`]: ../std/fmt/index.html
1210     ///
1211     /// # Examples
1212     ///
1213     /// ```
1214     /// // the panic message for these assertions is the stringified value of the
1215     /// // expression given.
1216     /// assert!(true);
1217     ///
1218     /// fn some_computation() -> bool { true } // a very simple function
1219     ///
1220     /// assert!(some_computation());
1221     ///
1222     /// // assert with a custom message
1223     /// let x = true;
1224     /// assert!(x, "x wasn't true!");
1225     ///
1226     /// let a = 3; let b = 27;
1227     /// assert!(a + b == 30, "a = {}, b = {}", a, b);
1228     /// ```
1229     #[stable(feature = "rust1", since = "1.0.0")]
1230     #[rustc_builtin_macro]
1231     #[rustc_macro_transparency = "semitransparent"]
1232     pub macro assert {
1233         ($cond:expr) => ({ /* compiler built-in */ }),
1234         ($cond:expr,) => ({ /* compiler built-in */ }),
1235         ($cond:expr, $($arg:tt)+) => ({ /* compiler built-in */ })
1236     }
1237
1238     /// Inline assembly.
1239     #[unstable(feature = "asm", issue = "29722",
1240                reason = "inline assembly is not stable enough for use and is subject to change")]
1241     #[rustc_builtin_macro]
1242     #[rustc_macro_transparency = "semitransparent"]
1243     pub macro asm("assembly template"
1244                   : $("output"(operand),)*
1245                   : $("input"(operand),)*
1246                   : $("clobbers",)*
1247                   : $("options",)*) { /* compiler built-in */ }
1248
1249     /// Module-level inline assembly.
1250     #[unstable(feature = "global_asm", issue = "35119",
1251                reason = "`global_asm!` is not stable enough for use and is subject to change")]
1252     #[rustc_builtin_macro]
1253     #[rustc_macro_transparency = "semitransparent"]
1254     pub macro global_asm("assembly") { /* compiler built-in */ }
1255
1256     /// Prints passed tokens into the standard output.
1257     #[unstable(feature = "log_syntax", issue = "29598",
1258                reason = "`log_syntax!` is not stable enough for use and is subject to change")]
1259     #[rustc_builtin_macro]
1260     #[rustc_macro_transparency = "semitransparent"]
1261     pub macro log_syntax($($arg:tt)*) { /* compiler built-in */ }
1262
1263     /// Enables or disables tracing functionality used for debugging other macros.
1264     #[unstable(feature = "trace_macros", issue = "29598",
1265                reason = "`trace_macros` is not stable enough for use and is subject to change")]
1266     #[rustc_builtin_macro]
1267     #[rustc_macro_transparency = "semitransparent"]
1268     pub macro trace_macros {
1269         (true) => ({ /* compiler built-in */ }),
1270         (false) => ({ /* compiler built-in */ })
1271     }
1272
1273     /// Attribute macro applied to a function to turn it into a unit test.
1274     #[stable(feature = "rust1", since = "1.0.0")]
1275     #[allow_internal_unstable(test, rustc_attrs)]
1276     #[rustc_builtin_macro]
1277     #[rustc_macro_transparency = "semitransparent"]
1278     pub macro test($item:item) { /* compiler built-in */ }
1279
1280     /// Attribute macro applied to a function to turn it into a benchmark test.
1281     #[unstable(feature = "test", issue = "50297",
1282                reason = "`bench` is a part of custom test frameworks which are unstable")]
1283     #[allow_internal_unstable(test, rustc_attrs)]
1284     #[rustc_builtin_macro]
1285     #[rustc_macro_transparency = "semitransparent"]
1286     pub macro bench($item:item) { /* compiler built-in */ }
1287
1288     /// An implementation detail of the `#[test]` and `#[bench]` macros.
1289     #[unstable(feature = "custom_test_frameworks", issue = "50297",
1290                reason = "custom test frameworks are an unstable feature")]
1291     #[allow_internal_unstable(test, rustc_attrs)]
1292     #[rustc_builtin_macro]
1293     #[rustc_macro_transparency = "semitransparent"]
1294     pub macro test_case($item:item) { /* compiler built-in */ }
1295
1296     /// Attribute macro applied to a static to register it as a global allocator.
1297     #[stable(feature = "global_allocator", since = "1.28.0")]
1298     #[allow_internal_unstable(rustc_attrs)]
1299     #[rustc_builtin_macro]
1300     #[rustc_macro_transparency = "semitransparent"]
1301     pub macro global_allocator($item:item) { /* compiler built-in */ }
1302
1303     /// Derive macro generating an impl of the trait `Clone`.
1304     #[rustc_builtin_macro]
1305     #[rustc_macro_transparency = "semitransparent"]
1306     #[stable(feature = "rust1", since = "1.0.0")]
1307     #[allow_internal_unstable(core_intrinsics, derive_clone_copy)]
1308     pub macro Clone($item:item) { /* compiler built-in */ }
1309
1310     /// Derive macro generating an impl of the trait `Copy`.
1311     #[rustc_builtin_macro]
1312     #[rustc_macro_transparency = "semitransparent"]
1313     #[stable(feature = "rust1", since = "1.0.0")]
1314     #[allow_internal_unstable(core_intrinsics, derive_clone_copy)]
1315     pub macro Copy($item:item) { /* compiler built-in */ }
1316
1317     /// Derive macro generating an impl of the trait `Debug`.
1318     #[rustc_builtin_macro]
1319     #[rustc_macro_transparency = "semitransparent"]
1320     #[stable(feature = "rust1", since = "1.0.0")]
1321     #[allow_internal_unstable(core_intrinsics)]
1322     pub macro Debug($item:item) { /* compiler built-in */ }
1323
1324     /// Derive macro generating an impl of the trait `Default`.
1325     #[rustc_builtin_macro]
1326     #[rustc_macro_transparency = "semitransparent"]
1327     #[stable(feature = "rust1", since = "1.0.0")]
1328     #[allow_internal_unstable(core_intrinsics)]
1329     pub macro Default($item:item) { /* compiler built-in */ }
1330
1331     /// Derive macro generating an impl of the trait `Eq`.
1332     #[rustc_builtin_macro]
1333     #[rustc_macro_transparency = "semitransparent"]
1334     #[stable(feature = "rust1", since = "1.0.0")]
1335     #[allow_internal_unstable(core_intrinsics, derive_eq)]
1336     pub macro Eq($item:item) { /* compiler built-in */ }
1337
1338     /// Derive macro generating an impl of the trait `Hash`.
1339     #[rustc_builtin_macro]
1340     #[rustc_macro_transparency = "semitransparent"]
1341     #[stable(feature = "rust1", since = "1.0.0")]
1342     #[allow_internal_unstable(core_intrinsics)]
1343     pub macro Hash($item:item) { /* compiler built-in */ }
1344
1345     /// Derive macro generating an impl of the trait `Ord`.
1346     #[rustc_builtin_macro]
1347     #[rustc_macro_transparency = "semitransparent"]
1348     #[stable(feature = "rust1", since = "1.0.0")]
1349     #[allow_internal_unstable(core_intrinsics)]
1350     pub macro Ord($item:item) { /* compiler built-in */ }
1351
1352     /// Derive macro generating an impl of the trait `PartialEq`.
1353     #[rustc_builtin_macro]
1354     #[rustc_macro_transparency = "semitransparent"]
1355     #[stable(feature = "rust1", since = "1.0.0")]
1356     #[allow_internal_unstable(core_intrinsics)]
1357     pub macro PartialEq($item:item) { /* compiler built-in */ }
1358
1359     /// Derive macro generating an impl of the trait `PartialOrd`.
1360     #[rustc_builtin_macro]
1361     #[rustc_macro_transparency = "semitransparent"]
1362     #[stable(feature = "rust1", since = "1.0.0")]
1363     #[allow_internal_unstable(core_intrinsics)]
1364     pub macro PartialOrd($item:item) { /* compiler built-in */ }
1365
1366     /// Unstable implementation detail of the `rustc` compiler, do not use.
1367     #[rustc_builtin_macro]
1368     #[rustc_macro_transparency = "semitransparent"]
1369     #[stable(feature = "rust1", since = "1.0.0")]
1370     #[allow_internal_unstable(core_intrinsics, libstd_sys_internals)]
1371     pub macro RustcDecodable($item:item) { /* compiler built-in */ }
1372
1373     /// Unstable implementation detail of the `rustc` compiler, do not use.
1374     #[rustc_builtin_macro]
1375     #[rustc_macro_transparency = "semitransparent"]
1376     #[stable(feature = "rust1", since = "1.0.0")]
1377     #[allow_internal_unstable(core_intrinsics)]
1378     pub macro RustcEncodable($item:item) { /* compiler built-in */ }
1379 }