src/libcore/macros.rs

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