user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rollup merge of #145943 - dianne:format-args-assign-docs, r=joboet

Browse source 
stdlib docs: document lifetime extension for `format_args!`'s arguments

Since rust-lang/rust#140748 is stable and rust-lang/rust#92698 is closed, the section about `format_args!`'s argument lifetime limitation is outdated. I've updated it to point to the Reference docs, which will specify lifetime extension rules for builtin macros once rust-lang/reference#1980 or equivalent is merged.

I've also taken the liberty of updating one of the doctests to assign the result of `format_args!` to a variable, both to provide an example and because I think it reads a little better.

r? `@m-ou-se`
This commit is contained in:
Matthias Krüger 2025-10-07 17:42:10 +02:00 • committed by GitHub
commit bce59abf1e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 12 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

19
library/core/src/macros/mod.rs
View file

@ -951,8 +951,9 @@ pub(crate) mod builtin {
/// format string in `format_args!`.
///
/// ```rust
/// let debug = format!("{:?}", format_args!("{} foo {:?}", 1, 2));
/// let display = format!("{}", format_args!("{} foo {:?}", 1, 2));
/// let args = format_args!("{} foo {:?}", 1, 2);
/// let debug = format!("{args:?}");
/// let display = format!("{args}");
/// assert_eq!("1 foo 2", display);
/// assert_eq!(display, debug);
/// ```
@ -976,13 +977,17 @@ pub(crate) mod builtin {
/// assert_eq!(s, format!("hello {}", "world"));
/// ```
///
/// # Lifetime limitation
/// # Argument lifetimes
///
/// Except when no formatting arguments are used,
/// the produced `fmt::Arguments` value borrows temporary values,
/// which means it can only be used within the same expression
/// and cannot be stored for later use.
/// This is a known limitation, see [#92698](https://github.com/rust-lang/rust/issues/92698).
/// the produced `fmt::Arguments` value borrows temporary values.
/// To allow it to be stored for later use, the arguments' lifetimes, as well as those of
/// temporaries they borrow, may be [extended] when `format_args!` appears in the initializer
/// expression of a `let` statement. The syntactic rules used to determine when temporaries'
/// lifetimes are extended are documented in the [Reference].
///
/// [extended]: ../reference/destructors.html#temporary-lifetime-extension
/// [Reference]: ../reference/destructors.html#extending-based-on-expressions
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_diagnostic_item = "format_args_macro"]
#[allow_internal_unsafe]