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 //! format!("{} {}", 1, 2); // => "1 2"
21 //! format!("{:04}", 42); // => "0042" with leading zeros
24 //! From these, you can see that the first argument is a format string. It is
25 //! required by the compiler for this to be a string literal; it cannot be a
26 //! variable passed in (in order to perform validity checking). The compiler
27 //! will then parse the format string and determine if the list of arguments
28 //! provided is suitable to pass to this format string.
30 //! To convert a single value to a string, use the [`to_string`] method. This
31 //! will use the [`Display`] formatting trait.
33 //! ## Positional parameters
35 //! Each formatting argument is allowed to specify which value argument it's
36 //! referencing, and if omitted it is assumed to be "the next argument". For
37 //! example, the format string `{} {} {}` would take three parameters, and they
38 //! would be formatted in the same order as they're given. The format string
39 //! `{2} {1} {0}`, however, would format arguments in reverse order.
41 //! Things can get a little tricky once you start intermingling the two types of
42 //! positional specifiers. The "next argument" specifier can be thought of as an
43 //! iterator over the argument. Each time a "next argument" specifier is seen,
44 //! the iterator advances. This leads to behavior like this:
47 //! format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2"
50 //! The internal iterator over the argument has not been advanced by the time
51 //! the first `{}` is seen, so it prints the first argument. Then upon reaching
52 //! the second `{}`, the iterator has advanced forward to the second argument.
53 //! Essentially, parameters which explicitly name their argument do not affect
54 //! parameters which do not name an argument in terms of positional specifiers.
56 //! A format string is required to use all of its arguments, otherwise it is a
57 //! compile-time error. You may refer to the same argument more than once in the
60 //! ## Named parameters
62 //! Rust itself does not have a Python-like equivalent of named parameters to a
63 //! function, but the [`format!`] macro is a syntax extension which allows it to
64 //! leverage named parameters. Named parameters are listed at the end of the
65 //! argument list and have the syntax:
68 //! identifier '=' expression
71 //! For example, the following [`format!`] expressions all use named argument:
74 //! format!("{argument}", argument = "test"); // => "test"
75 //! format!("{name} {}", 1, name = 2); // => "2 1"
76 //! format!("{a} {c} {b}", a="a", b='b', c=3); // => "a 3 b"
79 //! It is not valid to put positional parameters (those without names) after
80 //! arguments which have names. Like with positional parameters, it is not
81 //! valid to provide named parameters that are unused by the format string.
85 //! Each argument's type is dictated by the format string.
86 //! There are various parameters which require a particular type, however.
87 //! An example is the `{:.*}` syntax, which sets the number of decimal places
88 //! in floating-point types:
91 //! let formatted_number = format!("{:.*}", 2, 1.234567);
93 //! assert_eq!("1.23", formatted_number)
96 //! If this syntax is used, then the number of characters to print precedes the
97 //! actual object being formatted, and the number of characters must have the
100 //! ## Formatting traits
102 //! When requesting that an argument be formatted with a particular type, you
103 //! are actually requesting that an argument ascribes to a particular trait.
104 //! This allows multiple actual types to be formatted via `{:x}` (like [`i8`] as
105 //! well as [`isize`]). The current mapping of types to traits is:
107 //! * *nothing* ⇒ [`Display`]
108 //! * `?` ⇒ [`Debug`]
109 //! * `x?` ⇒ [`Debug`] with lower-case hexadecimal integers
110 //! * `X?` ⇒ [`Debug`] with upper-case hexadecimal integers
111 //! * `o` ⇒ [`Octal`](trait.Octal.html)
112 //! * `x` ⇒ [`LowerHex`](trait.LowerHex.html)
113 //! * `X` ⇒ [`UpperHex`](trait.UpperHex.html)
114 //! * `p` ⇒ [`Pointer`](trait.Pointer.html)
115 //! * `b` ⇒ [`Binary`]
116 //! * `e` ⇒ [`LowerExp`](trait.LowerExp.html)
117 //! * `E` ⇒ [`UpperExp`](trait.UpperExp.html)
119 //! What this means is that any type of argument which implements the
120 //! [`fmt::Binary`][`Binary`] trait can then be formatted with `{:b}`. Implementations
121 //! are provided for these traits for a number of primitive types by the
122 //! standard library as well. If no format is specified (as in `{}` or `{:6}`),
123 //! then the format trait used is the [`Display`] trait.
125 //! When implementing a format trait for your own type, you will have to
126 //! implement a method of the signature:
129 //! # #![allow(dead_code)]
131 //! # struct Foo; // our custom type
132 //! # impl fmt::Display for Foo {
133 //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
134 //! # write!(f, "testing, testing")
138 //! Your type will be passed as `self` by-reference, and then the function
139 //! should emit output into the `f.buf` stream. It is up to each format trait
140 //! implementation to correctly adhere to the requested formatting parameters.
141 //! The values of these parameters will be listed in the fields of the
142 //! [`Formatter`] struct. In order to help with this, the [`Formatter`] struct also
143 //! provides some helper methods.
145 //! Additionally, the return value of this function is [`fmt::Result`] which is a
146 //! type alias of [`Result`]`<(), `[`std::fmt::Error`]`>`. Formatting implementations
147 //! should ensure that they propagate errors from the [`Formatter`][`Formatter`] (e.g., when
148 //! calling [`write!`]). However, they should never return errors spuriously. That
149 //! is, a formatting implementation must and may only return an error if the
150 //! passed-in [`Formatter`] returns an error. This is because, contrary to what
151 //! the function signature might suggest, string formatting is an infallible
152 //! operation. This function only returns a result because writing to the
153 //! underlying stream might fail and it must provide a way to propagate the fact
154 //! that an error has occurred back up the stack.
156 //! An example of implementing the formatting traits would look
163 //! struct Vector2D {
168 //! impl fmt::Display for Vector2D {
169 //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
170 //! // The `f` value implements the `Write` trait, which is what the
171 //! // write! macro is expecting. Note that this formatting ignores the
172 //! // various flags provided to format strings.
173 //! write!(f, "({}, {})", self.x, self.y)
177 //! // Different traits allow different forms of output of a type. The meaning
178 //! // of this format is to print the magnitude of a vector.
179 //! impl fmt::Binary for Vector2D {
180 //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
181 //! let magnitude = (self.x * self.x + self.y * self.y) as f64;
182 //! let magnitude = magnitude.sqrt();
184 //! // Respect the formatting flags by using the helper method
185 //! // `pad_integral` on the Formatter object. See the method
186 //! // documentation for details, and the function `pad` can be used
187 //! // to pad strings.
188 //! let decimals = f.precision().unwrap_or(3);
189 //! let string = format!("{:.*}", decimals, magnitude);
190 //! f.pad_integral(true, "", &string)
195 //! let myvector = Vector2D { x: 3, y: 4 };
197 //! println!("{}", myvector); // => "(3, 4)"
198 //! println!("{:?}", myvector); // => "Vector2D {x: 3, y:4}"
199 //! println!("{:10.3b}", myvector); // => " 5.000"
203 //! ### `fmt::Display` vs `fmt::Debug`
205 //! These two formatting traits have distinct purposes:
207 //! - [`fmt::Display`][`Display`] implementations assert that the type can be faithfully
208 //! represented as a UTF-8 string at all times. It is **not** expected that
209 //! all types implement the [`Display`] trait.
210 //! - [`fmt::Debug`][`Debug`] implementations should be implemented for **all** public types.
211 //! Output will typically represent the internal state as faithfully as possible.
212 //! The purpose of the [`Debug`] trait is to facilitate debugging Rust code. In
213 //! most cases, using `#[derive(Debug)]` is sufficient and recommended.
215 //! Some examples of the output from both traits:
218 //! assert_eq!(format!("{} {:?}", 3, 4), "3 4");
219 //! assert_eq!(format!("{} {:?}", 'a', 'b'), "a 'b'");
220 //! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\"");
223 //! ## Related macros
225 //! There are a number of related macros in the [`format!`] family. The ones that
226 //! are currently implemented are:
228 //! ```ignore (only-for-syntax-highlight)
229 //! format! // described above
230 //! write! // first argument is a &mut io::Write, the destination
231 //! writeln! // same as write but appends a newline
232 //! print! // the format string is printed to the standard output
233 //! println! // same as print but appends a newline
234 //! eprint! // the format string is printed to the standard error
235 //! eprintln! // same as eprint but appends a newline
236 //! format_args! // described below.
241 //! This and [`writeln!`] are two macros which are used to emit the format string
242 //! to a specified stream. This is used to prevent intermediate allocations of
243 //! format strings and instead directly write the output. Under the hood, this
244 //! function is actually invoking the [`write_fmt`] function defined on the
245 //! [`std::io::Write`] trait. Example usage is:
248 //! # #![allow(unused_must_use)]
249 //! use std::io::Write;
250 //! let mut w = Vec::new();
251 //! write!(&mut w, "Hello {}!", "world");
256 //! This and [`println!`] emit their output to stdout. Similarly to the [`write!`]
257 //! macro, the goal of these macros is to avoid intermediate allocations when
258 //! printing output. Example usage is:
261 //! print!("Hello {}!", "world");
262 //! println!("I have a newline {}", "character at the end");
266 //! The [`eprint!`] and [`eprintln!`] macros are identical to
267 //! [`print!`] and [`println!`], respectively, except they emit their
268 //! output to stderr.
270 //! ### `format_args!`
272 //! This is a curious macro which is used to safely pass around
273 //! an opaque object describing the format string. This object
274 //! does not require any heap allocations to create, and it only
275 //! references information on the stack. Under the hood, all of
276 //! the related macros are implemented in terms of this. First
277 //! off, some example usage is:
280 //! # #![allow(unused_must_use)]
282 //! use std::io::{self, Write};
284 //! let mut some_writer = io::stdout();
285 //! write!(&mut some_writer, "{}", format_args!("print with a {}", "macro"));
287 //! fn my_fmt_fn(args: fmt::Arguments) {
288 //! write!(&mut io::stdout(), "{}", args);
290 //! my_fmt_fn(format_args!(", or a {} too", "function"));
293 //! The result of the [`format_args!`] macro is a value of type [`fmt::Arguments`].
294 //! This structure can then be passed to the [`write`] and [`format`] functions
295 //! inside this module in order to process the format string.
296 //! The goal of this macro is to even further prevent intermediate allocations
297 //! when dealing formatting strings.
299 //! For example, a logging library could use the standard formatting syntax, but
300 //! it would internally pass around this structure until it has been determined
301 //! where output should go to.
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 ] '}'
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 := identifier | '?' | ''
323 //! count := parameter | integer
324 //! parameter := argument '$'
327 //! # Formatting Parameters
329 //! Each argument being formatted can be transformed by a number of formatting
330 //! parameters (corresponding to `format_spec` in the syntax above). These
331 //! parameters affect the string representation of what's being formatted.
333 //! ## Fill/Alignment
335 //! The fill character is provided normally in conjunction with the
336 //! [`width`](#width)
337 //! parameter. This indicates that if the value being formatted is smaller than
338 //! `width` some extra characters will be printed around it. The extra
339 //! characters are specified by `fill`, and the alignment can be one of the
340 //! following options:
342 //! * `<` - the argument is left-aligned in `width` columns
343 //! * `^` - the argument is center-aligned in `width` columns
344 //! * `>` - the argument is right-aligned in `width` columns
346 //! Note that alignment may not be implemented by some types. A good way
347 //! to ensure padding is applied is to format your input, then use this
348 //! resulting string to pad your output.
352 //! These can all be interpreted as flags for a particular formatter.
354 //! * `+` - This is intended for numeric types and indicates that the sign
355 //! should always be printed. Positive signs are never printed by
356 //! default, and the negative sign is only printed by default for the
357 //! `Signed` trait. This flag indicates that the correct sign (`+` or `-`)
358 //! should always be printed.
359 //! * `-` - Currently not used
360 //! * `#` - This flag is indicates that the "alternate" form of printing should
361 //! be used. The alternate forms are:
362 //! * `#?` - pretty-print the [`Debug`] formatting
363 //! * `#x` - precedes the argument with a `0x`
364 //! * `#X` - precedes the argument with a `0x`
365 //! * `#b` - precedes the argument with a `0b`
366 //! * `#o` - precedes the argument with a `0o`
367 //! * `0` - This is used to indicate for integer formats that the padding should
368 //! both be done with a `0` character as well as be sign-aware. A format
369 //! like `{:08}` would yield `00000001` for the integer `1`, while the
370 //! same format would yield `-0000001` for the integer `-1`. Notice that
371 //! the negative version has one fewer zero than the positive version.
372 //! Note that padding zeroes are always placed after the sign (if any)
373 //! and before the digits. When used together with the `#` flag, a similar
374 //! rule applies: padding zeroes are inserted after the prefix but before
379 //! This is a parameter for the "minimum width" that the format should take up.
380 //! If the value's string does not fill up this many characters, then the
381 //! padding specified by fill/alignment will be used to take up the required
384 //! The default [fill/alignment](#fillalignment) for non-numerics is a space and
385 //! left-aligned. The
386 //! defaults for numeric formatters is also a space but with right-alignment. If
387 //! the `0` flag is specified for numerics, then the implicit fill character is
390 //! The value for the width can also be provided as a [`usize`] in the list of
391 //! parameters by using the dollar syntax indicating that the second argument is
392 //! a [`usize`] specifying the width, for example:
395 //! // All of these print "Hello x !"
396 //! println!("Hello {:5}!", "x");
397 //! println!("Hello {:1$}!", "x", 5);
398 //! println!("Hello {1:0$}!", 5, "x");
399 //! println!("Hello {:width$}!", "x", width = 5);
402 //! Referring to an argument with the dollar syntax does not affect the "next
403 //! argument" counter, so it's usually a good idea to refer to arguments by
404 //! position, or use named arguments.
408 //! For non-numeric types, this can be considered a "maximum width". If the resulting string is
409 //! longer than this width, then it is truncated down to this many characters and that truncated
410 //! value is emitted with proper `fill`, `alignment` and `width` if those parameters are set.
412 //! For integral types, this is ignored.
414 //! For floating-point types, this indicates how many digits after the decimal point should be
417 //! There are three possible ways to specify the desired `precision`:
419 //! 1. An integer `.N`:
421 //! the integer `N` itself is the precision.
423 //! 2. An integer or name followed by dollar sign `.N$`:
425 //! use format *argument* `N` (which must be a `usize`) as the precision.
427 //! 3. An asterisk `.*`:
429 //! `.*` means that this `{...}` is associated with *two* format inputs rather than one: the
430 //! first input holds the `usize` precision, and the second holds the value to print. Note that
431 //! in this case, if one uses the format string `{<arg>:<spec>.*}`, then the `<arg>` part refers
432 //! to the *value* to print, and the `precision` must come in the input preceding `<arg>`.
434 //! For example, the following calls all print the same thing `Hello x is 0.01000`:
437 //! // Hello {arg 0 ("x")} is {arg 1 (0.01) with precision specified inline (5)}
438 //! println!("Hello {0} is {1:.5}", "x", 0.01);
440 //! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision specified in arg 0 (5)}
441 //! println!("Hello {1} is {2:.0$}", 5, "x", 0.01);
443 //! // Hello {arg 0 ("x")} is {arg 2 (0.01) with precision specified in arg 1 (5)}
444 //! println!("Hello {0} is {2:.1$}", "x", 5, 0.01);
446 //! // Hello {next arg ("x")} is {second of next two args (0.01) with precision
447 //! // specified in first of next two args (5)}
448 //! println!("Hello {} is {:.*}", "x", 5, 0.01);
450 //! // Hello {next arg ("x")} is {arg 2 (0.01) with precision
451 //! // specified in its predecessor (5)}
452 //! println!("Hello {} is {2:.*}", "x", 5, 0.01);
454 //! // Hello {next arg ("x")} is {arg "number" (0.01) with precision specified
455 //! // in arg "prec" (5)}
456 //! println!("Hello {} is {number:.prec$}", "x", prec = 5, number = 0.01);
462 //! println!("{}, `{name:.*}` has 3 fractional digits", "Hello", 3, name=1234.56);
463 //! println!("{}, `{name:.*}` has 3 characters", "Hello", 3, name="1234.56");
464 //! println!("{}, `{name:>8.*}` has 3 right-aligned characters", "Hello", 3, name="1234.56");
467 //! print two significantly different things:
470 //! Hello, `1234.560` has 3 fractional digits
471 //! Hello, `123` has 3 characters
472 //! Hello, ` 123` has 3 right-aligned characters
477 //! The literal characters `{` and `}` may be included in a string by preceding
478 //! them with the same character. For example, the `{` character is escaped with
479 //! `{{` and the `}` character is escaped with `}}`.
481 //! [`usize`]: ../../std/primitive.usize.html
482 //! [`isize`]: ../../std/primitive.isize.html
483 //! [`i8`]: ../../std/primitive.i8.html
484 //! [`Display`]: trait.Display.html
485 //! [`Binary`]: trait.Binary.html
486 //! [`fmt::Result`]: type.Result.html
487 //! [`Result`]: ../../std/result/enum.Result.html
488 //! [`std::fmt::Error`]: struct.Error.html
489 //! [`Formatter`]: struct.Formatter.html
490 //! [`write!`]: ../../std/macro.write.html
491 //! [`Debug`]: trait.Debug.html
492 //! [`format!`]: ../../std/macro.format.html
493 //! [`to_string`]: ../../std/string/trait.ToString.html
494 //! [`writeln!`]: ../../std/macro.writeln.html
495 //! [`write_fmt`]: ../../std/io/trait.Write.html#method.write_fmt
496 //! [`std::io::Write`]: ../../std/io/trait.Write.html
497 //! [`print!`]: ../../std/macro.print.html
498 //! [`println!`]: ../../std/macro.println.html
499 //! [`eprint!`]: ../../std/macro.eprint.html
500 //! [`eprintln!`]: ../../std/macro.eprintln.html
501 //! [`write!`]: ../../std/macro.write.html
502 //! [`format_args!`]: ../../std/macro.format_args.html
503 //! [`fmt::Arguments`]: struct.Arguments.html
504 //! [`write`]: fn.write.html
505 //! [`format`]: fn.format.html
507 #![stable(feature = "rust1", since = "1.0.0")]
509 #[unstable(feature = "fmt_internals", issue = "0")]
510 pub use core::fmt::rt;
511 #[stable(feature = "rust1", since = "1.0.0")]
512 pub use core::fmt::{Formatter, Result, Write};
513 #[stable(feature = "rust1", since = "1.0.0")]
514 pub use core::fmt::{Binary, Octal};
515 #[stable(feature = "rust1", since = "1.0.0")]
516 pub use core::fmt::{Debug, Display};
517 #[stable(feature = "rust1", since = "1.0.0")]
518 pub use core::fmt::{LowerHex, Pointer, UpperHex};
519 #[stable(feature = "rust1", since = "1.0.0")]
520 pub use core::fmt::{LowerExp, UpperExp};
521 #[stable(feature = "rust1", since = "1.0.0")]
522 pub use core::fmt::Error;
523 #[stable(feature = "rust1", since = "1.0.0")]
524 pub use core::fmt::{write, ArgumentV1, Arguments};
525 #[stable(feature = "rust1", since = "1.0.0")]
526 pub use core::fmt::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple};
527 #[stable(feature = "fmt_flags_align", since = "1.28.0")]
528 pub use core::fmt::{Alignment};
532 /// The `format` function takes an [`Arguments`] struct and returns the resulting
533 /// formatted string.
535 /// The [`Arguments`] instance can be created with the [`format_args!`] macro.
544 /// let s = fmt::format(format_args!("Hello, {}!", "world"));
545 /// assert_eq!(s, "Hello, world!");
548 /// Please note that using [`format!`] might be preferable.
552 /// let s = format!("Hello, {}!", "world");
553 /// assert_eq!(s, "Hello, world!");
556 /// [`Arguments`]: struct.Arguments.html
557 /// [`format_args!`]: ../../std/macro.format_args.html
558 /// [`format!`]: ../../std/macro.format.html
559 #[stable(feature = "rust1", since = "1.0.0")]
560 pub fn format(args: Arguments<'_>) -> string::String {
561 let capacity = args.estimated_capacity();
562 let mut output = string::String::with_capacity(capacity);
565 .expect("a formatting trait implementation returned an error");