Add `format_args_capture` to the unstable book

1 files changed, 47 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/library-features/format-args-capture.md b/src/doc/unstable-book/src/library-features/format-args-capture.md
new file mode 100644
index 00000000000..64b1b3d81bd
--- /dev/null
+++ b/src/doc/unstable-book/src/library-features/format-args-capture.md
@@ -0,0 +1,47 @@
+# `format_args_capture`
+
+The tracking issue for this feature is: [#67984]
+
+[#67984]: https://github.com/rust-lang/rust/issues/67984
+
+------------------------
+
+Enables `format_args!` (and macros which use `format_args!` in their implementation, such
+as `format!`, `print!` and `panic!`) to capture variables from the surrounding scope.
+This avoids the need to pass named parameters when the binding in question
+already exists in scope.
+
+```rust
+#![feature(format_args_capture)]
+
+let (person, species, name) = ("Charlie Brown", "dog", "Snoopy");
+
+// captures named argument `person`
+print!("Hello {person}");
+
+// captures named arguments `species` and `name`
+format!("The {species}'s name is {name}.");
+```
+
+This also works for formatting parameters such as width and precision:
+
+```rust
+#![feature(format_args_capture)]
+
+let precision = 2;
+let s = format!("{:.precision$}", 1.324223);
+
+assert_eq!(&s, "1.32");
+```
+
+A non-exhaustive list of macros which benefit from this functionality include:
+- `format!`
+- `print!` and `println!`
+- `eprint!` and `eprintln!`
+- `write!` and `writeln!`
+- `panic!`
+- `unreachable!`
+- `unimplemented!`
+- `todo!`
+- `assert!` and similar
+- macros in many thirdparty crates, such as `log`