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