diff --git a/library/alloc/src/fmt.rs b/library/alloc/src/fmt.rs index 501a6353b2c97..d794b4f672d88 100644 --- a/library/alloc/src/fmt.rs +++ b/library/alloc/src/fmt.rs @@ -84,6 +84,7 @@ //! //! If a named parameter does not appear in the argument list, `format!` will //! reference a variable with that name in the current scope. +//! (Rust 1.58 and later; in [`panic!`], requires Rust 2021.) //! //! ``` //! let argument = 2 + 2; diff --git a/library/alloc/src/macros.rs b/library/alloc/src/macros.rs index 22c19243e7f53..6f1b6b800e351 100644 --- a/library/alloc/src/macros.rs +++ b/library/alloc/src/macros.rs @@ -73,10 +73,12 @@ macro_rules! vec { /// /// The first argument `format!` receives is a format string. This must be a string /// literal. The power of the formatting string is in the `{}`s contained. -/// /// Additional parameters passed to `format!` replace the `{}`s within the /// formatting string in the order given unless named or positional parameters -/// are used; see [`std::fmt`] for more information. +/// are used. +/// +/// See [the formatting syntax documentation in `std::fmt`](../std/fmt/index.html) +/// for details. /// /// A common use for `format!` is concatenation and interpolation of strings. /// The same convention is used with [`print!`] and [`write!`] macros, @@ -85,7 +87,6 @@ macro_rules! vec { /// To convert a single value to a string, use the [`to_string`] method. This /// will use the [`Display`] formatting trait. /// -/// [`std::fmt`]: ../std/fmt/index.html /// [`print!`]: ../std/macro.print.html /// [`write!`]: core::write /// [`to_string`]: crate::string::ToString diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index 83f33ca007af1..503bd10de4c98 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -849,7 +849,8 @@ pub(crate) mod builtin { /// assert_eq!(display, debug); /// ``` /// - /// For more information, see the documentation in [`std::fmt`]. + /// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) + /// for details of the macro argument syntax, and further information. /// /// [`Display`]: crate::fmt::Display /// [`Debug`]: crate::fmt::Debug diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md index 98fb7e9e41d7a..46b9bc7151d26 100644 --- a/library/core/src/macros/panic.md +++ b/library/core/src/macros/panic.md @@ -9,7 +9,7 @@ tests. `panic!` is closely tied with the `unwrap` method of both `panic!` when they are set to [`None`] or [`Err`] variants. When using `panic!()` you can specify a string payload, that is built using -the [`format!`] syntax. That payload is used when injecting the panic into +the [`format!` syntax]. That payload is used when injecting the panic into the calling Rust thread, causing the thread to panic entirely. The behavior of the default `std` hook, i.e. the code that runs directly @@ -55,7 +55,7 @@ For more detailed information about error handling check out the [book] or the [`panic_any`]: ../std/panic/fn.panic_any.html [`Box`]: ../std/boxed/struct.Box.html [`Any`]: crate::any::Any -[`format!`]: ../std/macro.format.html +[`format!` syntax]: ../std/fmt/index.html [book]: ../book/ch09-00-error-handling.html [`std::result`]: ../std/result/index.html @@ -64,6 +64,25 @@ For more detailed information about error handling check out the [book] or the If the main thread panics it will terminate all your threads and end your program with code `101`. +# Editions + +In Rust Editions prior to 2021, `std::panic!(x)` with a single +argument is equivalent to +[`std::panic::panic_any(x)`](../std/panic/fn.panic_any.html). +This is true even if the argument is a string literal. + +For example, in Rust 2015 `panic!("problem: {reason}")` panics with a +payload of literally `"problem: {reason}"` (a `&'static str`), which +is probably not what was intended. In current Rust this usage +captures and formats a variable `reason` from the surrounding scope. + +In Rust editions prior to 2021, `core::panic!(x)` requires that +`x` be `&str`, but does not require it to be a literal. In Rust 2021, +these cases must be written `panic!("{}", x)`. + +In Rust 2021 and later, `panic!` always requires a format string and +the applicable format arguments, and is the same in `core` and `std`. + # Examples ```should_panic diff --git a/library/std/src/macros.rs b/library/std/src/macros.rs index c597fb5df45d2..2479f101809ae 100644 --- a/library/std/src/macros.rs +++ b/library/std/src/macros.rs @@ -30,6 +30,9 @@ macro_rules! panic { /// Use `print!` only for the primary output of your program. Use /// [`eprint!`] instead to print error and progress messages. /// +/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) +/// for details of the macro argument syntax. +/// /// [flush]: crate::io::Write::flush /// /// # Panics @@ -76,6 +79,9 @@ macro_rules! print { /// Use `println!` only for the primary output of your program. Use /// [`eprintln!`] instead to print error and progress messages. /// +/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) +/// for details of the macro argument syntax. +/// /// [`std::fmt`]: crate::fmt /// /// # Panics @@ -116,6 +122,9 @@ macro_rules! println { /// [`io::stderr`]: crate::io::stderr /// [`io::stdout`]: crate::io::stdout /// +/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) +/// for details of the macro argument syntax. +/// /// # Panics /// /// Panics if writing to `io::stderr` fails. @@ -144,6 +153,9 @@ macro_rules! eprint { /// Use `eprintln!` only for error and progress messages. Use `println!` /// instead for the primary output of your program. /// +/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) +/// for details of the macro argument syntax. +/// /// [`io::stderr`]: crate::io::stderr /// [`io::stdout`]: crate::io::stdout ///