src/libcore/macros.rs

   1 /// Entry point of thread panic. For details, see `std::macros`.
   2 #[macro_export]
   3 #[allow_internal_unstable(core_panic, __rust_unstable_column)]
   4 #[stable(feature = "core", since = "1.6.0")]
   5 macro_rules! panic {
   6     () => (
   7         panic!("explicit panic")
   8     );
   9     ($msg:expr) => ({
  10         $crate::panicking::panic(&($msg, file!(), line!(), __rust_unstable_column!()))
  11     });
  12     ($msg:expr,) => (
  13         panic!($msg)
  14     );
  15     ($fmt:expr, $($arg:tt)+) => ({
  16         $crate::panicking::panic_fmt(format_args!($fmt, $($arg)*),
  17                                      &(file!(), line!(), __rust_unstable_column!()))
  18     });
  19 }
  20
  21 /// Asserts that two expressions are equal to each other (using [`PartialEq`]).
  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 /// [`PartialEq`]: cmp/trait.PartialEq.html
  30 /// [`assert!`]: macro.assert.html
  31 ///
  32 /// # Examples
  33 ///
  34 /// ```
  35 /// let a = 3;
  36 /// let b = 1 + 2;
  37 /// assert_eq!(a, b);
  38 ///
  39 /// assert_eq!(a, b, "we are testing addition with {} and {}", a, b);
  40 /// ```
  41 #[macro_export]
  42 #[stable(feature = "rust1", since = "1.0.0")]
  43 macro_rules! assert_eq {
  44     ($left:expr, $right:expr) => ({
  45         match (&$left, &$right) {
  46             (left_val, right_val) => {
  47                 if !(*left_val == *right_val) {
  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                     panic!(r#"assertion failed: `(left == right)`
  52   left: `{:?}`,
  53  right: `{:?}`"#, &*left_val, &*right_val)
  54                 }
  55             }
  56         }
  57     });
  58     ($left:expr, $right:expr,) => ({
  59         assert_eq!($left, $right)
  60     });
  61     ($left:expr, $right:expr, $($arg:tt)+) => ({
  62         match (&($left), &($right)) {
  63             (left_val, right_val) => {
  64                 if !(*left_val == *right_val) {
  65                     // The reborrows below are intentional. Without them, the stack slot for the
  66                     // borrow is initialized even before the values are compared, leading to a
  67                     // noticeable slow down.
  68                     panic!(r#"assertion failed: `(left == right)`
  69   left: `{:?}`,
  70  right: `{:?}`: {}"#, &*left_val, &*right_val,
  71                            format_args!($($arg)+))
  72                 }
  73             }
  74         }
  75     });
  76 }
  77
  78 /// Asserts that two expressions are not equal to each other (using [`PartialEq`]).
  79 ///
  80 /// On panic, this macro will print the values of the expressions with their
  81 /// debug representations.
  82 ///
  83 /// Like [`assert!`], this macro has a second form, where a custom
  84 /// panic message can be provided.
  85 ///
  86 /// [`PartialEq`]: cmp/trait.PartialEq.html
  87 /// [`assert!`]: macro.assert.html
  88 ///
  89 /// # Examples
  90 ///
  91 /// ```
  92 /// let a = 3;
  93 /// let b = 2;
  94 /// assert_ne!(a, b);
  95 ///
  96 /// assert_ne!(a, b, "we are testing that the values are not equal");
  97 /// ```
  98 #[macro_export]
  99 #[stable(feature = "assert_ne", since = "1.13.0")]
 100 macro_rules! assert_ne {
 101     ($left:expr, $right:expr) => ({
 102         match (&$left, &$right) {
 103             (left_val, right_val) => {
 104                 if *left_val == *right_val {
 105                     // The reborrows below are intentional. Without them, the stack slot for the
 106                     // borrow is initialized even before the values are compared, leading to a
 107                     // noticeable slow down.
 108                     panic!(r#"assertion failed: `(left != right)`
 109   left: `{:?}`,
 110  right: `{:?}`"#, &*left_val, &*right_val)
 111                 }
 112             }
 113         }
 114     });
 115     ($left:expr, $right:expr,) => {
 116         assert_ne!($left, $right)
 117     };
 118     ($left:expr, $right:expr, $($arg:tt)+) => ({
 119         match (&($left), &($right)) {
 120             (left_val, right_val) => {
 121                 if *left_val == *right_val {
 122                     // The reborrows below are intentional. Without them, the stack slot for the
 123                     // borrow is initialized even before the values are compared, leading to a
 124                     // noticeable slow down.
 125                     panic!(r#"assertion failed: `(left != right)`
 126   left: `{:?}`,
 127  right: `{:?}`: {}"#, &*left_val, &*right_val,
 128                            format_args!($($arg)+))
 129                 }
 130             }
 131         }
 132     });
 133 }
 134
 135 /// Ensure that a boolean expression is `true` at runtime.
 136 ///
 137 /// This will invoke the [`panic!`] macro if the provided expression cannot be
 138 /// evaluated to `true` at runtime.
 139 ///
 140 /// Like [`assert!`], this macro also has a second version, where a custom panic
 141 /// message can be provided.
 142 ///
 143 /// # Uses
 144 ///
 145 /// Unlike [`assert!`], `debug_assert!` statements are only enabled in non
 146 /// optimized builds by default. An optimized build will omit all
 147 /// `debug_assert!` statements unless `-C debug-assertions` is passed to the
 148 /// compiler. This makes `debug_assert!` useful for checks that are too
 149 /// expensive to be present in a release build but may be helpful during
 150 /// development.
 151 ///
 152 /// An unchecked assertion allows a program in an inconsistent state to keep
 153 /// running, which might have unexpected consequences but does not introduce
 154 /// unsafety as long as this only happens in safe code. The performance cost
 155 /// of assertions, is however, not measurable in general. Replacing [`assert!`]
 156 /// with `debug_assert!` is thus only encouraged after thorough profiling, and
 157 /// more importantly, only in safe code!
 158 ///
 159 /// [`panic!`]: macro.panic.html
 160 /// [`assert!`]: macro.assert.html
 161 ///
 162 /// # Examples
 163 ///
 164 /// ```
 165 /// // the panic message for these assertions is the stringified value of the
 166 /// // expression given.
 167 /// debug_assert!(true);
 168 ///
 169 /// fn some_expensive_computation() -> bool { true } // a very simple function
 170 /// debug_assert!(some_expensive_computation());
 171 ///
 172 /// // assert with a custom message
 173 /// let x = true;
 174 /// debug_assert!(x, "x wasn't true!");
 175 ///
 176 /// let a = 3; let b = 27;
 177 /// debug_assert!(a + b == 30, "a = {}, b = {}", a, b);
 178 /// ```
 179 #[macro_export]
 180 #[stable(feature = "rust1", since = "1.0.0")]
 181 macro_rules! debug_assert {
 182     ($($arg:tt)*) => (if cfg!(debug_assertions) { assert!($($arg)*); })
 183 }
 184
 185 /// Asserts that two expressions are equal to each other.
 186 ///
 187 /// On panic, this macro will print the values of the expressions with their
 188 /// debug representations.
 189 ///
 190 /// Unlike [`assert_eq!`], `debug_assert_eq!` statements are only enabled in non
 191 /// optimized builds by default. An optimized build will omit all
 192 /// `debug_assert_eq!` statements unless `-C debug-assertions` is passed to the
 193 /// compiler. This makes `debug_assert_eq!` useful for checks that are too
 194 /// expensive to be present in a release build but may be helpful during
 195 /// development.
 196 ///
 197 /// [`assert_eq!`]: ../std/macro.assert_eq.html
 198 ///
 199 /// # Examples
 200 ///
 201 /// ```
 202 /// let a = 3;
 203 /// let b = 1 + 2;
 204 /// debug_assert_eq!(a, b);
 205 /// ```
 206 #[macro_export]
 207 #[stable(feature = "rust1", since = "1.0.0")]
 208 macro_rules! debug_assert_eq {
 209     ($($arg:tt)*) => (if cfg!(debug_assertions) { assert_eq!($($arg)*); })
 210 }
 211
 212 /// Asserts that two expressions are not equal to each other.
 213 ///
 214 /// On panic, this macro will print the values of the expressions with their
 215 /// debug representations.
 216 ///
 217 /// Unlike [`assert_ne!`], `debug_assert_ne!` statements are only enabled in non
 218 /// optimized builds by default. An optimized build will omit all
 219 /// `debug_assert_ne!` statements unless `-C debug-assertions` is passed to the
 220 /// compiler. This makes `debug_assert_ne!` useful for checks that are too
 221 /// expensive to be present in a release build but may be helpful during
 222 /// development.
 223 ///
 224 /// [`assert_ne!`]: ../std/macro.assert_ne.html
 225 ///
 226 /// # Examples
 227 ///
 228 /// ```
 229 /// let a = 3;
 230 /// let b = 2;
 231 /// debug_assert_ne!(a, b);
 232 /// ```
 233 #[macro_export]
 234 #[stable(feature = "assert_ne", since = "1.13.0")]
 235 macro_rules! debug_assert_ne {
 236     ($($arg:tt)*) => (if cfg!(debug_assertions) { assert_ne!($($arg)*); })
 237 }
 238
 239 /// Helper macro for reducing boilerplate code for matching `Result` together
 240 /// with converting downstream errors.
 241 ///
 242 /// The `?` operator was added to replace `try!` and should be used instead.
 243 /// Furthermore, `try` is a reserved word in Rust 2018, so if you must use
 244 /// it, you will need to use the [raw-identifier syntax][ris]: `r#try`.
 245 ///
 246 /// [ris]: https://doc.rust-lang.org/nightly/rust-by-example/compatibility/raw_identifiers.html
 247 ///
 248 /// `try!` matches the given [`Result`]. In case of the `Ok` variant, the
 249 /// expression has the value of the wrapped value.
 250 ///
 251 /// In case of the `Err` variant, it retrieves the inner error. `try!` then
 252 /// performs conversion using `From`. This provides automatic conversion
 253 /// between specialized errors and more general ones. The resulting
 254 /// error is then immediately returned.
 255 ///
 256 /// Because of the early return, `try!` can only be used in functions that
 257 /// return [`Result`].
 258 ///
 259 /// [`Result`]: ../std/result/enum.Result.html
 260 ///
 261 /// # Examples
 262 ///
 263 /// ```
 264 /// use std::io;
 265 /// use std::fs::File;
 266 /// use std::io::prelude::*;
 267 ///
 268 /// enum MyError {
 269 ///     FileWriteError
 270 /// }
 271 ///
 272 /// impl From<io::Error> for MyError {
 273 ///     fn from(e: io::Error) -> MyError {
 274 ///         MyError::FileWriteError
 275 ///     }
 276 /// }
 277 ///
 278 /// // The preferred method of quick returning Errors
 279 /// fn write_to_file_question() -> Result<(), MyError> {
 280 ///     let mut file = File::create("my_best_friends.txt")?;
 281 ///     file.write_all(b"This is a list of my best friends.")?;
 282 ///     Ok(())
 283 /// }
 284 ///
 285 /// // The previous method of quick returning Errors
 286 /// fn write_to_file_using_try() -> Result<(), MyError> {
 287 ///     let mut file = r#try!(File::create("my_best_friends.txt"));
 288 ///     r#try!(file.write_all(b"This is a list of my best friends."));
 289 ///     Ok(())
 290 /// }
 291 ///
 292 /// // This is equivalent to:
 293 /// fn write_to_file_using_match() -> Result<(), MyError> {
 294 ///     let mut file = r#try!(File::create("my_best_friends.txt"));
 295 ///     match file.write_all(b"This is a list of my best friends.") {
 296 ///         Ok(v) => v,
 297 ///         Err(e) => return Err(From::from(e)),
 298 ///     }
 299 ///     Ok(())
 300 /// }
 301 /// ```
 302 #[macro_export]
 303 #[stable(feature = "rust1", since = "1.0.0")]
 304 #[doc(alias = "?")]
 305 macro_rules! r#try {
 306     ($expr:expr) => (match $expr {
 307         $crate::result::Result::Ok(val) => val,
 308         $crate::result::Result::Err(err) => {
 309             return $crate::result::Result::Err($crate::convert::From::from(err))
 310         }
 311     });
 312     ($expr:expr,) => (r#try!($expr));
 313 }
 314
 315 /// Write formatted data into a buffer.
 316 ///
 317 /// This macro accepts a format string, a list of arguments, and a 'writer'. Arguments will be
 318 /// formatted according to the specified format string and the result will be passed to the writer.
 319 /// The writer may be any value with a `write_fmt` method; generally this comes from an
 320 /// implementation of either the [`std::fmt::Write`] or the [`std::io::Write`] trait. The macro
 321 /// returns whatever the `write_fmt` method returns; commonly a [`std::fmt::Result`], or an
 322 /// [`io::Result`].
 323 ///
 324 /// See [`std::fmt`] for more information on the format string syntax.
 325 ///
 326 /// [`std::fmt`]: ../std/fmt/index.html
 327 /// [`std::fmt::Write`]: ../std/fmt/trait.Write.html
 328 /// [`std::io::Write`]: ../std/io/trait.Write.html
 329 /// [`std::fmt::Result`]: ../std/fmt/type.Result.html
 330 /// [`io::Result`]: ../std/io/type.Result.html
 331 ///
 332 /// # Examples
 333 ///
 334 /// ```
 335 /// use std::io::Write;
 336 ///
 337 /// let mut w = Vec::new();
 338 /// write!(&mut w, "test").unwrap();
 339 /// write!(&mut w, "formatted {}", "arguments").unwrap();
 340 ///
 341 /// assert_eq!(w, b"testformatted arguments");
 342 /// ```
 343 ///
 344 /// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
 345 /// implementing either, as objects do not typically implement both. However, the module must
 346 /// import the traits qualified so their names do not conflict:
 347 ///
 348 /// ```
 349 /// use std::fmt::Write as FmtWrite;
 350 /// use std::io::Write as IoWrite;
 351 ///
 352 /// let mut s = String::new();
 353 /// let mut v = Vec::new();
 354 /// write!(&mut s, "{} {}", "abc", 123).unwrap(); // uses fmt::Write::write_fmt
 355 /// write!(&mut v, "s = {:?}", s).unwrap(); // uses io::Write::write_fmt
 356 /// assert_eq!(v, b"s = \"abc 123\"");
 357 /// ```
 358 ///
 359 /// Note: This macro can be used in `no_std` setups as well.
 360 /// In a `no_std` setup you are responsible for the implementation details of the components.
 361 ///
 362 /// ```no_run
 363 /// # extern crate core;
 364 /// use core::fmt::Write;
 365 ///
 366 /// struct Example;
 367 ///
 368 /// impl Write for Example {
 369 ///     fn write_str(&mut self, _s: &str) -> core::fmt::Result {
 370 ///          unimplemented!();
 371 ///     }
 372 /// }
 373 ///
 374 /// let mut m = Example{};
 375 /// write!(&mut m, "Hello World").expect("Not written");
 376 /// ```
 377 #[macro_export]
 378 #[stable(feature = "rust1", since = "1.0.0")]
 379 macro_rules! write {
 380     ($dst:expr, $($arg:tt)*) => ($dst.write_fmt(format_args!($($arg)*)))
 381 }
 382
 383 /// Write formatted data into a buffer, with a newline appended.
 384 ///
 385 /// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
 386 /// (no additional CARRIAGE RETURN (`\r`/`U+000D`).
 387 ///
 388 /// For more information, see [`write!`]. For information on the format string syntax, see
 389 /// [`std::fmt`].
 390 ///
 391 /// [`write!`]: macro.write.html
 392 /// [`std::fmt`]: ../std/fmt/index.html
 393 ///
 394 ///
 395 /// # Examples
 396 ///
 397 /// ```
 398 /// use std::io::Write;
 399 ///
 400 /// let mut w = Vec::new();
 401 /// writeln!(&mut w).unwrap();
 402 /// writeln!(&mut w, "test").unwrap();
 403 /// writeln!(&mut w, "formatted {}", "arguments").unwrap();
 404 ///
 405 /// assert_eq!(&w[..], "\ntest\nformatted arguments\n".as_bytes());
 406 /// ```
 407 ///
 408 /// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
 409 /// implementing either, as objects do not typically implement both. However, the module must
 410 /// import the traits qualified so their names do not conflict:
 411 ///
 412 /// ```
 413 /// use std::fmt::Write as FmtWrite;
 414 /// use std::io::Write as IoWrite;
 415 ///
 416 /// let mut s = String::new();
 417 /// let mut v = Vec::new();
 418 /// writeln!(&mut s, "{} {}", "abc", 123).unwrap(); // uses fmt::Write::write_fmt
 419 /// writeln!(&mut v, "s = {:?}", s).unwrap(); // uses io::Write::write_fmt
 420 /// assert_eq!(v, b"s = \"abc 123\\n\"\n");
 421 /// ```
 422 #[macro_export]
 423 #[stable(feature = "rust1", since = "1.0.0")]
 424 #[allow_internal_unstable(format_args_nl)]
 425 macro_rules! writeln {
 426     ($dst:expr) => (
 427         write!($dst, "\n")
 428     );
 429     ($dst:expr,) => (
 430         writeln!($dst)
 431     );
 432     ($dst:expr, $($arg:tt)*) => (
 433         $dst.write_fmt(format_args_nl!($($arg)*))
 434     );
 435 }
 436
 437 /// A utility macro for indicating unreachable code.
 438 ///
 439 /// This is useful any time that the compiler can't determine that some code is unreachable. For
 440 /// example:
 441 ///
 442 /// * Match arms with guard conditions.
 443 /// * Loops that dynamically terminate.
 444 /// * Iterators that dynamically terminate.
 445 ///
 446 /// If the determination that the code is unreachable proves incorrect, the
 447 /// program immediately terminates with a [`panic!`]. The function [`unreachable_unchecked`],
 448 /// which belongs to the [`std::hint`] module, informs the compiler to
 449 /// optimize the code out of the release version entirely.
 450 ///
 451 /// [`panic!`]:  ../std/macro.panic.html
 452 /// [`unreachable_unchecked`]: ../std/hint/fn.unreachable_unchecked.html
 453 /// [`std::hint`]: ../std/hint/index.html
 454 ///
 455 /// # Panics
 456 ///
 457 /// This will always [`panic!`]
 458 ///
 459 /// [`panic!`]: ../std/macro.panic.html
 460 /// # Examples
 461 ///
 462 /// Match arms:
 463 ///
 464 /// ```
 465 /// # #[allow(dead_code)]
 466 /// fn foo(x: Option<i32>) {
 467 ///     match x {
 468 ///         Some(n) if n >= 0 => println!("Some(Non-negative)"),
 469 ///         Some(n) if n <  0 => println!("Some(Negative)"),
 470 ///         Some(_)           => unreachable!(), // compile error if commented out
 471 ///         None              => println!("None")
 472 ///     }
 473 /// }
 474 /// ```
 475 ///
 476 /// Iterators:
 477 ///
 478 /// ```
 479 /// # #[allow(dead_code)]
 480 /// fn divide_by_three(x: u32) -> u32 { // one of the poorest implementations of x/3
 481 ///     for i in 0.. {
 482 ///         if 3*i < i { panic!("u32 overflow"); }
 483 ///         if x < 3*i { return i-1; }
 484 ///     }
 485 ///     unreachable!();
 486 /// }
 487 /// ```
 488 #[macro_export]
 489 #[stable(feature = "rust1", since = "1.0.0")]
 490 macro_rules! unreachable {
 491     () => ({
 492         panic!("internal error: entered unreachable code")
 493     });
 494     ($msg:expr) => ({
 495         unreachable!("{}", $msg)
 496     });
 497     ($msg:expr,) => ({
 498         unreachable!($msg)
 499     });
 500     ($fmt:expr, $($arg:tt)*) => ({
 501         panic!(concat!("internal error: entered unreachable code: ", $fmt), $($arg)*)
 502     });
 503 }
 504
 505 /// A standardized placeholder for marking unfinished code.
 506 ///
 507 /// This can be useful if you are prototyping and are just looking to have your
 508 /// code type-check, or if you're implementing a trait that requires multiple
 509 /// methods, and you're only planning on using one of them.
 510 ///
 511 /// # Panics
 512 ///
 513 /// This will always [panic!](macro.panic.html)
 514 ///
 515 /// # Examples
 516 ///
 517 /// Here's an example of some in-progress code. We have a trait `Foo`:
 518 ///
 519 /// ```
 520 /// trait Foo {
 521 ///     fn bar(&self);
 522 ///     fn baz(&self);
 523 /// }
 524 /// ```
 525 ///
 526 /// We want to implement `Foo` on one of our types, but we also want to work on
 527 /// just `bar()` first. In order for our code to compile, we need to implement
 528 /// `baz()`, so we can use `unimplemented!`:
 529 ///
 530 /// ```
 531 /// # trait Foo {
 532 /// #     fn bar(&self);
 533 /// #     fn baz(&self);
 534 /// # }
 535 /// struct MyStruct;
 536 ///
 537 /// impl Foo for MyStruct {
 538 ///     fn bar(&self) {
 539 ///         // implementation goes here
 540 ///     }
 541 ///
 542 ///     fn baz(&self) {
 543 ///         // let's not worry about implementing baz() for now
 544 ///         unimplemented!();
 545 ///     }
 546 /// }
 547 ///
 548 /// fn main() {
 549 ///     let s = MyStruct;
 550 ///     s.bar();
 551 ///
 552 ///     // we aren't even using baz() yet, so this is fine.
 553 /// }
 554 /// ```
 555 #[macro_export]
 556 #[stable(feature = "rust1", since = "1.0.0")]
 557 macro_rules! unimplemented {
 558     () => (panic!("not yet implemented"));
 559     ($($arg:tt)+) => (panic!("not yet implemented: {}", format_args!($($arg)*)));
 560 }
 561
 562 /// A macro to create an array of [`MaybeUninit`]
 563 ///
 564 /// This macro constructs an uninitialized array of the type `[MaybeUninit<K>; N]`.
 565 ///
 566 /// [`MaybeUninit`]: mem/union.MaybeUninit.html
 567 #[macro_export]
 568 #[unstable(feature = "maybe_uninit_array", issue = "53491")]
 569 macro_rules! uninitialized_array {
 570     // This `into_initialized` is safe because an array of `MaybeUninit` does not
 571     // require initialization.
 572     // FIXME(#49147): Could be replaced by an array initializer, once those can
 573     // be any const expression.
 574     ($t:ty; $size:expr) => (unsafe {
 575         MaybeUninit::<[MaybeUninit<$t>; $size]>::uninitialized().into_initialized()
 576     });
 577 }
 578
 579 /// Built-in macros to the compiler itself.
 580 ///
 581 /// These macros do not have any corresponding definition with a `macro_rules!`
 582 /// macro, but are documented here. Their implementations can be found hardcoded
 583 /// into libsyntax itself.
 584 ///
 585 /// For more information, see documentation for `std`'s macros.
 586 #[cfg(rustdoc)]
 587 mod builtin {
 588
 589     /// Unconditionally causes compilation to fail with the given error message when encountered.
 590     ///
 591     /// For more information, see the documentation for [`std::compile_error!`].
 592     ///
 593     /// [`std::compile_error!`]: ../std/macro.compile_error.html
 594     #[stable(feature = "compile_error_macro", since = "1.20.0")]
 595     #[rustc_doc_only_macro]
 596     macro_rules! compile_error {
 597         ($msg:expr) => ({ /* compiler built-in */ });
 598         ($msg:expr,) => ({ /* compiler built-in */ });
 599     }
 600
 601     /// The core macro for formatted string creation & output.
 602     ///
 603     /// For more information, see the documentation for [`std::format_args!`].
 604     ///
 605     /// [`std::format_args!`]: ../std/macro.format_args.html
 606     #[stable(feature = "rust1", since = "1.0.0")]
 607     #[rustc_doc_only_macro]
 608     macro_rules! format_args {
 609         ($fmt:expr) => ({ /* compiler built-in */ });
 610         ($fmt:expr, $($args:tt)*) => ({ /* compiler built-in */ });
 611     }
 612
 613     /// Inspect an environment variable at compile time.
 614     ///
 615     /// For more information, see the documentation for [`std::env!`].
 616     ///
 617     /// [`std::env!`]: ../std/macro.env.html
 618     #[stable(feature = "rust1", since = "1.0.0")]
 619     #[rustc_doc_only_macro]
 620     macro_rules! env {
 621         ($name:expr) => ({ /* compiler built-in */ });
 622         ($name:expr,) => ({ /* compiler built-in */ });
 623     }
 624
 625     /// Optionally inspect an environment variable at compile time.
 626     ///
 627     /// For more information, see the documentation for [`std::option_env!`].
 628     ///
 629     /// [`std::option_env!`]: ../std/macro.option_env.html
 630     #[stable(feature = "rust1", since = "1.0.0")]
 631     #[rustc_doc_only_macro]
 632     macro_rules! option_env {
 633         ($name:expr) => ({ /* compiler built-in */ });
 634         ($name:expr,) => ({ /* compiler built-in */ });
 635     }
 636
 637     /// Concatenate identifiers into one identifier.
 638     ///
 639     /// For more information, see the documentation for [`std::concat_idents!`].
 640     ///
 641     /// [`std::concat_idents!`]: ../std/macro.concat_idents.html
 642     #[unstable(feature = "concat_idents_macro", issue = "29599")]
 643     #[rustc_doc_only_macro]
 644     macro_rules! concat_idents {
 645         ($($e:ident),+) => ({ /* compiler built-in */ });
 646         ($($e:ident,)+) => ({ /* compiler built-in */ });
 647     }
 648
 649     /// Concatenates literals into a static string slice.
 650     ///
 651     /// For more information, see the documentation for [`std::concat!`].
 652     ///
 653     /// [`std::concat!`]: ../std/macro.concat.html
 654     #[stable(feature = "rust1", since = "1.0.0")]
 655     #[rustc_doc_only_macro]
 656     macro_rules! concat {
 657         ($($e:expr),*) => ({ /* compiler built-in */ });
 658         ($($e:expr,)*) => ({ /* compiler built-in */ });
 659     }
 660
 661     /// A macro which expands to the line number on which it was invoked.
 662     ///
 663     /// For more information, see the documentation for [`std::line!`].
 664     ///
 665     /// [`std::line!`]: ../std/macro.line.html
 666     #[stable(feature = "rust1", since = "1.0.0")]
 667     #[rustc_doc_only_macro]
 668     macro_rules! line { () => ({ /* compiler built-in */ }) }
 669
 670     /// A macro which expands to the column number on which it was invoked.
 671     ///
 672     /// For more information, see the documentation for [`std::column!`].
 673     ///
 674     /// [`std::column!`]: ../std/macro.column.html
 675     #[stable(feature = "rust1", since = "1.0.0")]
 676     #[rustc_doc_only_macro]
 677     macro_rules! column { () => ({ /* compiler built-in */ }) }
 678
 679     /// A macro which expands to the file name from which it was invoked.
 680     ///
 681     /// For more information, see the documentation for [`std::file!`].
 682     ///
 683     /// [`std::file!`]: ../std/macro.file.html
 684     #[stable(feature = "rust1", since = "1.0.0")]
 685     #[rustc_doc_only_macro]
 686     macro_rules! file { () => ({ /* compiler built-in */ }) }
 687
 688     /// A macro which stringifies its arguments.
 689     ///
 690     /// For more information, see the documentation for [`std::stringify!`].
 691     ///
 692     /// [`std::stringify!`]: ../std/macro.stringify.html
 693     #[stable(feature = "rust1", since = "1.0.0")]
 694     #[rustc_doc_only_macro]
 695     macro_rules! stringify { ($($t:tt)*) => ({ /* compiler built-in */ }) }
 696
 697     /// Includes a utf8-encoded file as a string.
 698     ///
 699     /// For more information, see the documentation for [`std::include_str!`].
 700     ///
 701     /// [`std::include_str!`]: ../std/macro.include_str.html
 702     #[stable(feature = "rust1", since = "1.0.0")]
 703     #[rustc_doc_only_macro]
 704     macro_rules! include_str {
 705         ($file:expr) => ({ /* compiler built-in */ });
 706         ($file:expr,) => ({ /* compiler built-in */ });
 707     }
 708
 709     /// Includes a file as a reference to a byte array.
 710     ///
 711     /// For more information, see the documentation for [`std::include_bytes!`].
 712     ///
 713     /// [`std::include_bytes!`]: ../std/macro.include_bytes.html
 714     #[stable(feature = "rust1", since = "1.0.0")]
 715     #[rustc_doc_only_macro]
 716     macro_rules! include_bytes {
 717         ($file:expr) => ({ /* compiler built-in */ });
 718         ($file:expr,) => ({ /* compiler built-in */ });
 719     }
 720
 721     /// Expands to a string that represents the current module path.
 722     ///
 723     /// For more information, see the documentation for [`std::module_path!`].
 724     ///
 725     /// [`std::module_path!`]: ../std/macro.module_path.html
 726     #[stable(feature = "rust1", since = "1.0.0")]
 727     #[rustc_doc_only_macro]
 728     macro_rules! module_path { () => ({ /* compiler built-in */ }) }
 729
 730     /// Boolean evaluation of configuration flags, at compile-time.
 731     ///
 732     /// For more information, see the documentation for [`std::cfg!`].
 733     ///
 734     /// [`std::cfg!`]: ../std/macro.cfg.html
 735     #[stable(feature = "rust1", since = "1.0.0")]
 736     #[rustc_doc_only_macro]
 737     macro_rules! cfg { ($($cfg:tt)*) => ({ /* compiler built-in */ }) }
 738
 739     /// Parse a file as an expression or an item according to the context.
 740     ///
 741     /// For more information, see the documentation for [`std::include!`].
 742     ///
 743     /// [`std::include!`]: ../std/macro.include.html
 744     #[stable(feature = "rust1", since = "1.0.0")]
 745     #[rustc_doc_only_macro]
 746     macro_rules! include {
 747         ($file:expr) => ({ /* compiler built-in */ });
 748         ($file:expr,) => ({ /* compiler built-in */ });
 749     }
 750
 751     /// Ensure that a boolean expression is `true` at runtime.
 752     ///
 753     /// For more information, see the documentation for [`std::assert!`].
 754     ///
 755     /// [`std::assert!`]: ../std/macro.assert.html
 756     #[rustc_doc_only_macro]
 757     #[stable(feature = "rust1", since = "1.0.0")]
 758     macro_rules! assert {
 759         ($cond:expr) => ({ /* compiler built-in */ });
 760         ($cond:expr,) => ({ /* compiler built-in */ });
 761         ($cond:expr, $($arg:tt)+) => ({ /* compiler built-in */ });
 762     }
 763 }