1 //! Utilities for formatting and printing `String`s.
3 //! This module contains the runtime support for the [`format!`] syntax extension.
4 //! This macro is implemented in the compiler to emit calls to this module in
5 //! order to format arguments at runtime into strings.
9 //! The [`format!`] macro is intended to be familiar to those coming from C's
10 //! `printf`/`fprintf` functions or Python's `str.format` function.
12 //! Some examples of the [`format!`] extension are:
15 //! format!("Hello"); // => "Hello"
16 //! format!("Hello, {}!", "world"); // => "Hello, world!"
17 //! format!("The number is {}", 1); // => "The number is 1"
18 //! format!("{:?}", (3, 4)); // => "(3, 4)"
19 //! format!("{value}", value=4); // => "4"
20 //! let people = "Rustaceans";
21 //! format!("Hello {people}!"); // => "Hello Rustaceans!"
22 //! format!("{} {}", 1, 2); // => "1 2"
23 //! format!("{:04}", 42); // => "0042" with leading zeros
24 //! format!("{:#?}", (100, 200)); // => "(
30 //! From these, you can see that the first argument is a format string. It is
31 //! required by the compiler for this to be a string literal; it cannot be a
32 //! variable passed in (in order to perform validity checking). The compiler
33 //! will then parse the format string and determine if the list of arguments
34 //! provided is suitable to pass to this format string.
36 //! To convert a single value to a string, use the [`to_string`] method. This
37 //! will use the [`Display`] formatting trait.
39 //! ## Positional parameters
41 //! Each formatting argument is allowed to specify which value argument it's
42 //! referencing, and if omitted it is assumed to be "the next argument". For
43 //! example, the format string `{} {} {}` would take three parameters, and they
44 //! would be formatted in the same order as they're given. The format string
45 //! `{2} {1} {0}`, however, would format arguments in reverse order.
47 //! Things can get a little tricky once you start intermingling the two types of
48 //! positional specifiers. The "next argument" specifier can be thought of as an
49 //! iterator over the argument. Each time a "next argument" specifier is seen,
50 //! the iterator advances. This leads to behavior like this:
53 //! format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2"
56 //! The internal iterator over the argument has not been advanced by the time
57 //! the first `{}` is seen, so it prints the first argument. Then upon reaching
58 //! the second `{}`, the iterator has advanced forward to the second argument.
59 //! Essentially, parameters that explicitly name their argument do not affect
60 //! parameters that do not name an argument in terms of positional specifiers.
62 //! A format string is required to use all of its arguments, otherwise it is a
63 //! compile-time error. You may refer to the same argument more than once in the
66 //! ## Named parameters
68 //! Rust itself does not have a Python-like equivalent of named parameters to a
69 //! function, but the [`format!`] macro is a syntax extension that allows it to
70 //! leverage named parameters. Named parameters are listed at the end of the
71 //! argument list and have the syntax:
74 //! identifier '=' expression
77 //! For example, the following [`format!`] expressions all use named arguments:
80 //! format!("{argument}", argument = "test"); // => "test"
81 //! format!("{name} {}", 1, name = 2); // => "2 1"
82 //! format!("{a} {c} {b}", a="a", b='b', c=3); // => "a 3 b"
85 //! If a named parameter does not appear in the argument list, `format!` will
86 //! reference a variable with that name in the current scope.
89 //! let argument = 2 + 2;
90 //! format!("{argument}"); // => "4"
92 //! fn make_string(a: u32, b: &str) -> String {
93 //! format!("{b} {a}")
95 //! make_string(927, "label"); // => "label 927"
98 //! It is not valid to put positional parameters (those without names) after
99 //! arguments that have names. Like with positional parameters, it is not
100 //! valid to provide named parameters that are unused by the format string.
102 //! # Formatting Parameters
104 //! Each argument being formatted can be transformed by a number of formatting
105 //! parameters (corresponding to `format_spec` in [the syntax](#syntax)). These
106 //! parameters affect the string representation of what's being formatted.
111 //! // All of these print "Hello x !"
112 //! println!("Hello {:5}!", "x");
113 //! println!("Hello {:1$}!", "x", 5);
114 //! println!("Hello {1:0$}!", 5, "x");
115 //! println!("Hello {:width$}!", "x", width = 5);
117 //! println!("Hello {:width$}!", "x");
120 //! This is a parameter for the "minimum width" that the format should take up.
121 //! If the value's string does not fill up this many characters, then the
122 //! padding specified by fill/alignment will be used to take up the required
123 //! space (see below).
125 //! The value for the width can also be provided as a [`usize`] in the list of
126 //! parameters by adding a postfix `$`, indicating that the second argument is
127 //! a [`usize`] specifying the width.
129 //! Referring to an argument with the dollar syntax does not affect the "next
130 //! argument" counter, so it's usually a good idea to refer to arguments by
131 //! position, or use named arguments.
133 //! ## Fill/Alignment
136 //! assert_eq!(format!("Hello {:<5}!", "x"), "Hello x !");
137 //! assert_eq!(format!("Hello {:-<5}!", "x"), "Hello x----!");
138 //! assert_eq!(format!("Hello {:^5}!", "x"), "Hello x !");
139 //! assert_eq!(format!("Hello {:>5}!", "x"), "Hello x!");
142 //! The optional fill character and alignment is provided normally in conjunction with the
143 //! [`width`](#width) parameter. It must be defined before `width`, right after the `:`.
144 //! This indicates that if the value being formatted is smaller than
145 //! `width` some extra characters will be printed around it.
146 //! Filling comes in the following variants for different alignments:
148 //! * `[fill]<` - the argument is left-aligned in `width` columns
149 //! * `[fill]^` - the argument is center-aligned in `width` columns
150 //! * `[fill]>` - the argument is right-aligned in `width` columns
152 //! The default [fill/alignment](#fillalignment) for non-numerics is a space and
153 //! left-aligned. The
154 //! default for numeric formatters is also a space character but with right-alignment. If
155 //! the `0` flag (see below) is specified for numerics, then the implicit fill character is
158 //! Note that alignment might not be implemented by some types. In particular, it
159 //! is not generally implemented for the `Debug` trait. A good way to ensure
160 //! padding is applied is to format your input, then pad this resulting string
161 //! to obtain your output:
164 //! println!("Hello {:^15}!", format!("{:?}", Some("hi"))); // => "Hello Some("hi") !"
170 //! assert_eq!(format!("Hello {:+}!", 5), "Hello +5!");
171 //! assert_eq!(format!("{:#x}!", 27), "0x1b!");
172 //! assert_eq!(format!("Hello {:05}!", 5), "Hello 00005!");
173 //! assert_eq!(format!("Hello {:05}!", -5), "Hello -0005!");
174 //! assert_eq!(format!("{:#010x}!", 27), "0x0000001b!");
177 //! These are all flags altering the behavior of the formatter.
179 //! * `+` - This is intended for numeric types and indicates that the sign
180 //! should always be printed. Positive signs are never printed by
181 //! default, and the negative sign is only printed by default for signed values.
182 //! This flag indicates that the correct sign (`+` or `-`) should always be printed.
183 //! * `-` - Currently not used
184 //! * `#` - This flag indicates that the "alternate" form of printing should
185 //! be used. The alternate forms are:
186 //! * `#?` - pretty-print the [`Debug`] formatting (adds linebreaks and indentation)
187 //! * `#x` - precedes the argument with a `0x`
188 //! * `#X` - precedes the argument with a `0x`
189 //! * `#b` - precedes the argument with a `0b`
190 //! * `#o` - precedes the argument with a `0o`
191 //! * `0` - This is used to indicate for integer formats that the padding to `width` should
192 //! both be done with a `0` character as well as be sign-aware. A format
193 //! like `{:08}` would yield `00000001` for the integer `1`, while the
194 //! same format would yield `-0000001` for the integer `-1`. Notice that
195 //! the negative version has one fewer zero than the positive version.
196 //! Note that padding zeros are always placed after the sign (if any)
197 //! and before the digits. When used together with the `#` flag, a similar
198 //! rule applies: padding zeros are inserted after the prefix but before
199 //! the digits. The prefix is included in the total width.
203 //! For non-numeric types, this can be considered a "maximum width". If the resulting string is
204 //! longer than this width, then it is truncated down to this many characters and that truncated
205 //! value is emitted with proper `fill`, `alignment` and `width` if those parameters are set.
207 //! For integral types, this is ignored.
209 //! For floating-point types, this indicates how many digits after the decimal point should be
212 //! There are three possible ways to specify the desired `precision`:
214 //! 1. An integer `.N`:
216 //! the integer `N` itself is the precision.
218 //! 2. An integer or name followed by dollar sign `.N$`:
220 //! use format *argument* `N` (which must be a `usize`) as the precision.
222 //! 3. An asterisk `.*`:
224 //! `.*` means that this `{...}` is associated with *two* format inputs rather than one:
225 //! - If a format string in the fashion of `{:<spec>.*}` is used, then the first input holds
226 //! the `usize` precision, and the second holds the value to print.
227 //! - If a format string in the fashion of `{<arg>:<spec>.*}` is used, then the `<arg>` part
228 //! refers to the value to print, and the `precision` is taken like it was specified with an
229 //! omitted positional parameter (`{}` instead of `{<arg>:}`).
231 //! For example, the following calls all print the same thing `Hello x is 0.01000`:
234 //! // Hello {arg 0 ("x")} is {arg 1 (0.01) with precision specified inline (5)}
235 //! println!("Hello {0} is {1:.5}", "x", 0.01);
237 //! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision specified in arg 0 (5)}
238 //! println!("Hello {1} is {2:.0$}", 5, "x", 0.01);
240 //! // Hello {arg 0 ("x")} is {arg 2 (0.01) with precision specified in arg 1 (5)}
241 //! println!("Hello {0} is {2:.1$}", "x", 5, 0.01);
243 //! // Hello {next arg -> arg 0 ("x")} is {second of next two args -> arg 2 (0.01) with precision
244 //! // specified in first of next two args -> arg 1 (5)}
245 //! println!("Hello {} is {:.*}", "x", 5, 0.01);
247 //! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision
248 //! // specified in next arg -> arg 0 (5)}
249 //! println!("Hello {1} is {2:.*}", 5, "x", 0.01);
251 //! // Hello {next arg -> arg 0 ("x")} is {arg 2 (0.01) with precision
252 //! // specified in next arg -> arg 1 (5)}
253 //! println!("Hello {} is {2:.*}", "x", 5, 0.01);
255 //! // Hello {next arg -> arg 0 ("x")} is {arg "number" (0.01) with precision specified
256 //! // in arg "prec" (5)}
257 //! println!("Hello {} is {number:.prec$}", "x", prec = 5, number = 0.01);
263 //! println!("{}, `{name:.*}` has 3 fractional digits", "Hello", 3, name=1234.56);
264 //! println!("{}, `{name:.*}` has 3 characters", "Hello", 3, name="1234.56");
265 //! println!("{}, `{name:>8.*}` has 3 right-aligned characters", "Hello", 3, name="1234.56");
268 //! print three significantly different things:
271 //! Hello, `1234.560` has 3 fractional digits
272 //! Hello, `123` has 3 characters
273 //! Hello, ` 123` has 3 right-aligned characters
278 //! In some programming languages, the behavior of string formatting functions
279 //! depends on the operating system's locale setting. The format functions
280 //! provided by Rust's standard library do not have any concept of locale and
281 //! will produce the same results on all systems regardless of user
284 //! For example, the following code will always print `1.5` even if the system
285 //! locale uses a decimal separator other than a dot.
288 //! println!("The value is {}", 1.5);
293 //! The literal characters `{` and `}` may be included in a string by preceding
294 //! them with the same character. For example, the `{` character is escaped with
295 //! `{{` and the `}` character is escaped with `}}`.
298 //! assert_eq!(format!("Hello {{}}"), "Hello {}");
299 //! assert_eq!(format!("{{ Hello"), "{ Hello");
304 //! To summarize, here you can find the full grammar of format strings.
305 //! The syntax for the formatting language used is drawn from other languages,
306 //! so it should not be too alien. Arguments are formatted with Python-like
307 //! syntax, meaning that arguments are surrounded by `{}` instead of the C-like
308 //! `%`. The actual grammar for the formatting syntax is:
311 //! format_string := text [ maybe_format text ] *
312 //! maybe_format := '{' '{' | '}' '}' | format
313 //! format := '{' [ argument ] [ ':' format_spec ] [ ws ] * '}'
314 //! argument := integer | identifier
316 //! format_spec := [[fill]align][sign]['#']['0'][width]['.' precision]type
317 //! fill := character
318 //! align := '<' | '^' | '>'
319 //! sign := '+' | '-'
321 //! precision := count | '*'
322 //! type := '' | '?' | 'x?' | 'X?' | identifier
323 //! count := parameter | integer
324 //! parameter := argument '$'
326 //! In the above grammar,
327 //! - `text` must not contain any `'{'` or `'}'` characters,
328 //! - `ws` is any character for which [`char::is_whitespace`] returns `true`, has no semantic
329 //! meaning and is completely optional,
330 //! - `integer` is a decimal integer that may contain leading zeroes and
331 //! - `identifier` is an `IDENTIFIER_OR_KEYWORD` (not an `IDENTIFIER`) as defined by the [Rust language reference](https://doc.rust-lang.org/reference/identifiers.html).
333 //! # Formatting traits
335 //! When requesting that an argument be formatted with a particular type, you
336 //! are actually requesting that an argument ascribes to a particular trait.
337 //! This allows multiple actual types to be formatted via `{:x}` (like [`i8`] as
338 //! well as [`isize`]). The current mapping of types to traits is:
340 //! * *nothing* ⇒ [`Display`]
341 //! * `?` ⇒ [`Debug`]
342 //! * `x?` ⇒ [`Debug`] with lower-case hexadecimal integers
343 //! * `X?` ⇒ [`Debug`] with upper-case hexadecimal integers
344 //! * `o` ⇒ [`Octal`]
345 //! * `x` ⇒ [`LowerHex`]
346 //! * `X` ⇒ [`UpperHex`]
347 //! * `p` ⇒ [`Pointer`]
348 //! * `b` ⇒ [`Binary`]
349 //! * `e` ⇒ [`LowerExp`]
350 //! * `E` ⇒ [`UpperExp`]
352 //! What this means is that any type of argument which implements the
353 //! [`fmt::Binary`][`Binary`] trait can then be formatted with `{:b}`. Implementations
354 //! are provided for these traits for a number of primitive types by the
355 //! standard library as well. If no format is specified (as in `{}` or `{:6}`),
356 //! then the format trait used is the [`Display`] trait.
358 //! When implementing a format trait for your own type, you will have to
359 //! implement a method of the signature:
362 //! # #![allow(dead_code)]
364 //! # struct Foo; // our custom type
365 //! # impl fmt::Display for Foo {
366 //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
367 //! # write!(f, "testing, testing")
371 //! Your type will be passed as `self` by-reference, and then the function
372 //! should emit output into the Formatter `f` which implements `fmt::Write`. It is up to each
373 //! format trait implementation to correctly adhere to the requested formatting parameters.
374 //! The values of these parameters can be accessed with methods of the
375 //! [`Formatter`] struct. In order to help with this, the [`Formatter`] struct also
376 //! provides some helper methods.
378 //! Additionally, the return value of this function is [`fmt::Result`] which is a
379 //! type alias of <code>[Result]<(), [std::fmt::Error]></code>. Formatting implementations
380 //! should ensure that they propagate errors from the [`Formatter`] (e.g., when
381 //! calling [`write!`]). However, they should never return errors spuriously. That
382 //! is, a formatting implementation must and may only return an error if the
383 //! passed-in [`Formatter`] returns an error. This is because, contrary to what
384 //! the function signature might suggest, string formatting is an infallible
385 //! operation. This function only returns a result because writing to the
386 //! underlying stream might fail and it must provide a way to propagate the fact
387 //! that an error has occurred back up the stack.
389 //! An example of implementing the formatting traits would look
396 //! struct Vector2D {
401 //! impl fmt::Display for Vector2D {
402 //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
403 //! // The `f` value implements the `Write` trait, which is what the
404 //! // write! macro is expecting. Note that this formatting ignores the
405 //! // various flags provided to format strings.
406 //! write!(f, "({}, {})", self.x, self.y)
410 //! // Different traits allow different forms of output of a type. The meaning
411 //! // of this format is to print the magnitude of a vector.
412 //! impl fmt::Binary for Vector2D {
413 //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
414 //! let magnitude = (self.x * self.x + self.y * self.y) as f64;
415 //! let magnitude = magnitude.sqrt();
417 //! // Respect the formatting flags by using the helper method
418 //! // `pad_integral` on the Formatter object. See the method
419 //! // documentation for details, and the function `pad` can be used
420 //! // to pad strings.
421 //! let decimals = f.precision().unwrap_or(3);
422 //! let string = format!("{:.*}", decimals, magnitude);
423 //! f.pad_integral(true, "", &string)
428 //! let myvector = Vector2D { x: 3, y: 4 };
430 //! println!("{myvector}"); // => "(3, 4)"
431 //! println!("{myvector:?}"); // => "Vector2D {x: 3, y:4}"
432 //! println!("{myvector:10.3b}"); // => " 5.000"
436 //! ### `fmt::Display` vs `fmt::Debug`
438 //! These two formatting traits have distinct purposes:
440 //! - [`fmt::Display`][`Display`] implementations assert that the type can be faithfully
441 //! represented as a UTF-8 string at all times. It is **not** expected that
442 //! all types implement the [`Display`] trait.
443 //! - [`fmt::Debug`][`Debug`] implementations should be implemented for **all** public types.
444 //! Output will typically represent the internal state as faithfully as possible.
445 //! The purpose of the [`Debug`] trait is to facilitate debugging Rust code. In
446 //! most cases, using `#[derive(Debug)]` is sufficient and recommended.
448 //! Some examples of the output from both traits:
451 //! assert_eq!(format!("{} {:?}", 3, 4), "3 4");
452 //! assert_eq!(format!("{} {:?}", 'a', 'b'), "a 'b'");
453 //! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\"");
458 //! There are a number of related macros in the [`format!`] family. The ones that
459 //! are currently implemented are:
461 //! ```ignore (only-for-syntax-highlight)
462 //! format! // described above
463 //! write! // first argument is either a &mut io::Write or a &mut fmt::Write, the destination
464 //! writeln! // same as write but appends a newline
465 //! print! // the format string is printed to the standard output
466 //! println! // same as print but appends a newline
467 //! eprint! // the format string is printed to the standard error
468 //! eprintln! // same as eprint but appends a newline
469 //! format_args! // described below.
474 //! [`write!`] and [`writeln!`] are two macros which are used to emit the format string
475 //! to a specified stream. This is used to prevent intermediate allocations of
476 //! format strings and instead directly write the output. Under the hood, this
477 //! function is actually invoking the [`write_fmt`] function defined on the
478 //! [`std::io::Write`] and the [`std::fmt::Write`] trait. Example usage is:
481 //! # #![allow(unused_must_use)]
482 //! use std::io::Write;
483 //! let mut w = Vec::new();
484 //! write!(&mut w, "Hello {}!", "world");
489 //! This and [`println!`] emit their output to stdout. Similarly to the [`write!`]
490 //! macro, the goal of these macros is to avoid intermediate allocations when
491 //! printing output. Example usage is:
494 //! print!("Hello {}!", "world");
495 //! println!("I have a newline {}", "character at the end");
499 //! The [`eprint!`] and [`eprintln!`] macros are identical to
500 //! [`print!`] and [`println!`], respectively, except they emit their
501 //! output to stderr.
503 //! ### `format_args!`
505 //! [`format_args!`] is a curious macro used to safely pass around
506 //! an opaque object describing the format string. This object
507 //! does not require any heap allocations to create, and it only
508 //! references information on the stack. Under the hood, all of
509 //! the related macros are implemented in terms of this. First
510 //! off, some example usage is:
513 //! # #![allow(unused_must_use)]
515 //! use std::io::{self, Write};
517 //! let mut some_writer = io::stdout();
518 //! write!(&mut some_writer, "{}", format_args!("print with a {}", "macro"));
520 //! fn my_fmt_fn(args: fmt::Arguments) {
521 //! write!(&mut io::stdout(), "{}", args);
523 //! my_fmt_fn(format_args!(", or a {} too", "function"));
526 //! The result of the [`format_args!`] macro is a value of type [`fmt::Arguments`].
527 //! This structure can then be passed to the [`write`] and [`format`] functions
528 //! inside this module in order to process the format string.
529 //! The goal of this macro is to even further prevent intermediate allocations
530 //! when dealing with formatting strings.
532 //! For example, a logging library could use the standard formatting syntax, but
533 //! it would internally pass around this structure until it has been determined
534 //! where output should go to.
536 //! [`fmt::Result`]: Result "fmt::Result"
537 //! [Result]: core::result::Result "std::result::Result"
538 //! [std::fmt::Error]: Error "fmt::Error"
539 //! [`write`]: write() "fmt::write"
540 //! [`to_string`]: crate::string::ToString::to_string "ToString::to_string"
541 //! [`write_fmt`]: ../../std/io/trait.Write.html#method.write_fmt
542 //! [`std::io::Write`]: ../../std/io/trait.Write.html
543 //! [`std::fmt::Write`]: ../../std/fmt/trait.Write.html
544 //! [`print!`]: ../../std/macro.print.html "print!"
545 //! [`println!`]: ../../std/macro.println.html "println!"
546 //! [`eprint!`]: ../../std/macro.eprint.html "eprint!"
547 //! [`eprintln!`]: ../../std/macro.eprintln.html "eprintln!"
548 //! [`format_args!`]: ../../std/macro.format_args.html "format_args!"
549 //! [`fmt::Arguments`]: Arguments "fmt::Arguments"
550 //! [`format`]: format() "fmt::format"
552 #![stable(feature = "rust1", since = "1.0.0")]
554 #[unstable(feature = "fmt_internals", issue = "none")]
555 pub use core::fmt::rt;
556 #[stable(feature = "fmt_flags_align", since = "1.28.0")]
557 pub use core::fmt::Alignment;
558 #[stable(feature = "rust1", since = "1.0.0")]
559 pub use core::fmt::Error;
560 #[stable(feature = "rust1", since = "1.0.0")]
561 pub use core::fmt::{write, ArgumentV1, Arguments};
562 #[stable(feature = "rust1", since = "1.0.0")]
563 pub use core::fmt::{Binary, Octal};
564 #[stable(feature = "rust1", since = "1.0.0")]
565 pub use core::fmt::{Debug, Display};
566 #[stable(feature = "rust1", since = "1.0.0")]
567 pub use core::fmt::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple};
568 #[stable(feature = "rust1", since = "1.0.0")]
569 pub use core::fmt::{Formatter, Result, Write};
570 #[stable(feature = "rust1", since = "1.0.0")]
571 pub use core::fmt::{LowerExp, UpperExp};
572 #[stable(feature = "rust1", since = "1.0.0")]
573 pub use core::fmt::{LowerHex, Pointer, UpperHex};
575 #[cfg(not(no_global_oom_handling))]
578 /// The `format` function takes an [`Arguments`] struct and returns the resulting
579 /// formatted string.
581 /// The [`Arguments`] instance can be created with the [`format_args!`] macro.
590 /// let s = fmt::format(format_args!("Hello, {}!", "world"));
591 /// assert_eq!(s, "Hello, world!");
594 /// Please note that using [`format!`] might be preferable.
598 /// let s = format!("Hello, {}!", "world");
599 /// assert_eq!(s, "Hello, world!");
602 /// [`format_args!`]: core::format_args
603 /// [`format!`]: crate::format
604 #[cfg(not(no_global_oom_handling))]
606 #[stable(feature = "rust1", since = "1.0.0")]
608 pub fn format(args: Arguments<'_>) -> string::String {
610 fn format_cold(args: Arguments<'_>) -> string::String {
611 let capacity = args.estimated_capacity();
612 let mut output = string::String::with_capacity(capacity);
613 output.write_fmt(args).expect("a formatting trait implementation returned an error");
617 args.as_str().map_or_else(|| format_cold(args), crate::borrow::ToOwned::to_owned)