1 | //! Utilities for formatting and printing `String`s. |
2 | //! |
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. |
6 | //! |
7 | //! # Usage |
8 | //! |
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. |
11 | //! |
12 | //! Some examples of the [`format!`] extension are: |
13 | //! |
14 | //! ``` |
15 | //! # #![allow (unused_must_use)] |
16 | //! format!("Hello" ); // => "Hello" |
17 | //! format!("Hello, {}!" , "world" ); // => "Hello, world!" |
18 | //! format!("The number is {}" , 1); // => "The number is 1" |
19 | //! format!("{:?}" , (3, 4)); // => "(3, 4)" |
20 | //! format!("{value}" , value=4); // => "4" |
21 | //! let people = "Rustaceans" ; |
22 | //! format!("Hello {people}!" ); // => "Hello Rustaceans!" |
23 | //! format!("{} {}" , 1, 2); // => "1 2" |
24 | //! format!("{:04}" , 42); // => "0042" with leading zeros |
25 | //! format!("{:#?}" , (100, 200)); // => "( |
26 | //! // 100, |
27 | //! // 200, |
28 | //! // )" |
29 | //! ``` |
30 | //! |
31 | //! From these, you can see that the first argument is a format string. It is |
32 | //! required by the compiler for this to be a string literal; it cannot be a |
33 | //! variable passed in (in order to perform validity checking). The compiler |
34 | //! will then parse the format string and determine if the list of arguments |
35 | //! provided is suitable to pass to this format string. |
36 | //! |
37 | //! To convert a single value to a string, use the [`to_string`] method. This |
38 | //! will use the [`Display`] formatting trait. |
39 | //! |
40 | //! ## Positional parameters |
41 | //! |
42 | //! Each formatting argument is allowed to specify which value argument it's |
43 | //! referencing, and if omitted it is assumed to be "the next argument". For |
44 | //! example, the format string `{} {} {}` would take three parameters, and they |
45 | //! would be formatted in the same order as they're given. The format string |
46 | //! `{2} {1} {0}`, however, would format arguments in reverse order. |
47 | //! |
48 | //! Things can get a little tricky once you start intermingling the two types of |
49 | //! positional specifiers. The "next argument" specifier can be thought of as an |
50 | //! iterator over the argument. Each time a "next argument" specifier is seen, |
51 | //! the iterator advances. This leads to behavior like this: |
52 | //! |
53 | //! ``` |
54 | //! # #![allow(unused_must_use)] |
55 | //! format!("{1} {} {0} {}" , 1, 2); // => "2 1 1 2" |
56 | //! ``` |
57 | //! |
58 | //! The internal iterator over the argument has not been advanced by the time |
59 | //! the first `{}` is seen, so it prints the first argument. Then upon reaching |
60 | //! the second `{}`, the iterator has advanced forward to the second argument. |
61 | //! Essentially, parameters that explicitly name their argument do not affect |
62 | //! parameters that do not name an argument in terms of positional specifiers. |
63 | //! |
64 | //! A format string is required to use all of its arguments, otherwise it is a |
65 | //! compile-time error. You may refer to the same argument more than once in the |
66 | //! format string. |
67 | //! |
68 | //! ## Named parameters |
69 | //! |
70 | //! Rust itself does not have a Python-like equivalent of named parameters to a |
71 | //! function, but the [`format!`] macro is a syntax extension that allows it to |
72 | //! leverage named parameters. Named parameters are listed at the end of the |
73 | //! argument list and have the syntax: |
74 | //! |
75 | //! ```text |
76 | //! identifier '=' expression |
77 | //! ``` |
78 | //! |
79 | //! For example, the following [`format!`] expressions all use named arguments: |
80 | //! |
81 | //! ``` |
82 | //! # #![allow(unused_must_use)] |
83 | //! format!("{argument}" , argument = "test" ); // => "test" |
84 | //! format!("{name} {}" , 1, name = 2); // => "2 1" |
85 | //! format!("{a} {c} {b}" , a="a" , b='b' , c=3); // => "a 3 b" |
86 | //! ``` |
87 | //! |
88 | //! If a named parameter does not appear in the argument list, `format!` will |
89 | //! reference a variable with that name in the current scope. |
90 | //! |
91 | //! ``` |
92 | //! # #![allow(unused_must_use)] |
93 | //! let argument = 2 + 2; |
94 | //! format!("{argument}" ); // => "4" |
95 | //! |
96 | //! fn make_string(a: u32, b: &str) -> String { |
97 | //! format!("{b} {a}" ) |
98 | //! } |
99 | //! make_string(927, "label" ); // => "label 927" |
100 | //! ``` |
101 | //! |
102 | //! It is not valid to put positional parameters (those without names) after |
103 | //! arguments that have names. Like with positional parameters, it is not |
104 | //! valid to provide named parameters that are unused by the format string. |
105 | //! |
106 | //! # Formatting Parameters |
107 | //! |
108 | //! Each argument being formatted can be transformed by a number of formatting |
109 | //! parameters (corresponding to `format_spec` in [the syntax](#syntax)). These |
110 | //! parameters affect the string representation of what's being formatted. |
111 | //! |
112 | //! The colon `:` in format syntax divides identifier of the input data and |
113 | //! the formatting options, the colon itself does not change anything, only |
114 | //! introduces the options. |
115 | //! |
116 | //! ``` |
117 | //! let a = 5; |
118 | //! let b = &a; |
119 | //! println!("{a:e} {b:p}" ); // => 5e0 0x7ffe37b7273c |
120 | //! ``` |
121 | //! |
122 | //! ## Width |
123 | //! |
124 | //! ``` |
125 | //! // All of these print "Hello x !" |
126 | //! println!("Hello {:5}!" , "x" ); |
127 | //! println!("Hello {:1$}!" , "x" , 5); |
128 | //! println!("Hello {1:0$}!" , 5, "x" ); |
129 | //! println!("Hello {:width$}!" , "x" , width = 5); |
130 | //! let width = 5; |
131 | //! println!("Hello {:width$}!" , "x" ); |
132 | //! ``` |
133 | //! |
134 | //! This is a parameter for the "minimum width" that the format should take up. |
135 | //! If the value's string does not fill up this many characters, then the |
136 | //! padding specified by fill/alignment will be used to take up the required |
137 | //! space (see below). |
138 | //! |
139 | //! The value for the width can also be provided as a [`usize`] in the list of |
140 | //! parameters by adding a postfix `$`, indicating that the second argument is |
141 | //! a [`usize`] specifying the width. |
142 | //! |
143 | //! Referring to an argument with the dollar syntax does not affect the "next |
144 | //! argument" counter, so it's usually a good idea to refer to arguments by |
145 | //! position, or use named arguments. |
146 | //! |
147 | //! ## Fill/Alignment |
148 | //! |
149 | //! ``` |
150 | //! assert_eq!(format!("Hello {:<5}!" , "x" ), "Hello x !" ); |
151 | //! assert_eq!(format!("Hello {:-<5}!" , "x" ), "Hello x----!" ); |
152 | //! assert_eq!(format!("Hello {:^5}!" , "x" ), "Hello x !" ); |
153 | //! assert_eq!(format!("Hello {:>5}!" , "x" ), "Hello x!" ); |
154 | //! ``` |
155 | //! |
156 | //! The optional fill character and alignment is provided normally in conjunction with the |
157 | //! [`width`](#width) parameter. It must be defined before `width`, right after the `:`. |
158 | //! This indicates that if the value being formatted is smaller than |
159 | //! `width` some extra characters will be printed around it. |
160 | //! Filling comes in the following variants for different alignments: |
161 | //! |
162 | //! * `[fill]<` - the argument is left-aligned in `width` columns |
163 | //! * `[fill]^` - the argument is center-aligned in `width` columns |
164 | //! * `[fill]>` - the argument is right-aligned in `width` columns |
165 | //! |
166 | //! The default [fill/alignment](#fillalignment) for non-numerics is a space and |
167 | //! left-aligned. The |
168 | //! default for numeric formatters is also a space character but with right-alignment. If |
169 | //! the `0` flag (see below) is specified for numerics, then the implicit fill character is |
170 | //! `0`. |
171 | //! |
172 | //! Note that alignment might not be implemented by some types. In particular, it |
173 | //! is not generally implemented for the `Debug` trait. A good way to ensure |
174 | //! padding is applied is to format your input, then pad this resulting string |
175 | //! to obtain your output: |
176 | //! |
177 | //! ``` |
178 | //! println!("Hello {:^15}!" , format!("{:?}" , Some("hi" ))); // => "Hello Some("hi") !" |
179 | //! ``` |
180 | //! |
181 | //! ## Sign/`#`/`0` |
182 | //! |
183 | //! ``` |
184 | //! assert_eq!(format!("Hello {:+}!" , 5), "Hello +5!" ); |
185 | //! assert_eq!(format!("{:#x}!" , 27), "0x1b!" ); |
186 | //! assert_eq!(format!("Hello {:05}!" , 5), "Hello 00005!" ); |
187 | //! assert_eq!(format!("Hello {:05}!" , -5), "Hello -0005!" ); |
188 | //! assert_eq!(format!("{:#010x}!" , 27), "0x0000001b!" ); |
189 | //! ``` |
190 | //! |
191 | //! These are all flags altering the behavior of the formatter. |
192 | //! |
193 | //! * `+` - This is intended for numeric types and indicates that the sign |
194 | //! should always be printed. By default only the negative sign of signed values |
195 | //! is printed, and the sign of positive or unsigned values is omitted. |
196 | //! This flag indicates that the correct sign (`+` or `-`) should always be printed. |
197 | //! * `-` - Currently not used |
198 | //! * `#` - This flag indicates that the "alternate" form of printing should |
199 | //! be used. The alternate forms are: |
200 | //! * `#?` - pretty-print the [`Debug`] formatting (adds linebreaks and indentation) |
201 | //! * `#x` - precedes the argument with a `0x` |
202 | //! * `#X` - precedes the argument with a `0x` |
203 | //! * `#b` - precedes the argument with a `0b` |
204 | //! * `#o` - precedes the argument with a `0o` |
205 | //! |
206 | //! See [Formatting traits](#formatting-traits) for a description of what the `?`, `x`, `X`, |
207 | //! `b`, and `o` flags do. |
208 | //! |
209 | //! * `0` - This is used to indicate for integer formats that the padding to `width` should |
210 | //! both be done with a `0` character as well as be sign-aware. A format |
211 | //! like `{:08}` would yield `00000001` for the integer `1`, while the |
212 | //! same format would yield `-0000001` for the integer `-1`. Notice that |
213 | //! the negative version has one fewer zero than the positive version. |
214 | //! Note that padding zeros are always placed after the sign (if any) |
215 | //! and before the digits. When used together with the `#` flag, a similar |
216 | //! rule applies: padding zeros are inserted after the prefix but before |
217 | //! the digits. The prefix is included in the total width. |
218 | //! This flag overrides the [fill character and alignment flag](#fillalignment). |
219 | //! |
220 | //! ## Precision |
221 | //! |
222 | //! For non-numeric types, this can be considered a "maximum width". If the resulting string is |
223 | //! longer than this width, then it is truncated down to this many characters and that truncated |
224 | //! value is emitted with proper `fill`, `alignment` and `width` if those parameters are set. |
225 | //! |
226 | //! For integral types, this is ignored. |
227 | //! |
228 | //! For floating-point types, this indicates how many digits after the decimal point should be |
229 | //! printed. |
230 | //! |
231 | //! There are three possible ways to specify the desired `precision`: |
232 | //! |
233 | //! 1. An integer `.N`: |
234 | //! |
235 | //! the integer `N` itself is the precision. |
236 | //! |
237 | //! 2. An integer or name followed by dollar sign `.N$`: |
238 | //! |
239 | //! use format *argument* `N` (which must be a `usize`) as the precision. |
240 | //! |
241 | //! 3. An asterisk `.*`: |
242 | //! |
243 | //! `.*` means that this `{...}` is associated with *two* format inputs rather than one: |
244 | //! - If a format string in the fashion of `{:<spec>.*}` is used, then the first input holds |
245 | //! the `usize` precision, and the second holds the value to print. |
246 | //! - If a format string in the fashion of `{<arg>:<spec>.*}` is used, then the `<arg>` part |
247 | //! refers to the value to print, and the `precision` is taken like it was specified with an |
248 | //! omitted positional parameter (`{}` instead of `{<arg>:}`). |
249 | //! |
250 | //! For example, the following calls all print the same thing `Hello x is 0.01000`: |
251 | //! |
252 | //! ``` |
253 | //! // Hello {arg 0 ("x")} is {arg 1 (0.01) with precision specified inline (5)} |
254 | //! println!("Hello {0} is {1:.5}" , "x" , 0.01); |
255 | //! |
256 | //! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision specified in arg 0 (5)} |
257 | //! println!("Hello {1} is {2:.0$}" , 5, "x" , 0.01); |
258 | //! |
259 | //! // Hello {arg 0 ("x")} is {arg 2 (0.01) with precision specified in arg 1 (5)} |
260 | //! println!("Hello {0} is {2:.1$}" , "x" , 5, 0.01); |
261 | //! |
262 | //! // Hello {next arg -> arg 0 ("x")} is {second of next two args -> arg 2 (0.01) with precision |
263 | //! // specified in first of next two args -> arg 1 (5)} |
264 | //! println!("Hello {} is {:.*}" , "x" , 5, 0.01); |
265 | //! |
266 | //! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision |
267 | //! // specified in next arg -> arg 0 (5)} |
268 | //! println!("Hello {1} is {2:.*}" , 5, "x" , 0.01); |
269 | //! |
270 | //! // Hello {next arg -> arg 0 ("x")} is {arg 2 (0.01) with precision |
271 | //! // specified in next arg -> arg 1 (5)} |
272 | //! println!("Hello {} is {2:.*}" , "x" , 5, 0.01); |
273 | //! |
274 | //! // Hello {next arg -> arg 0 ("x")} is {arg "number" (0.01) with precision specified |
275 | //! // in arg "prec" (5)} |
276 | //! println!("Hello {} is {number:.prec$}" , "x" , prec = 5, number = 0.01); |
277 | //! ``` |
278 | //! |
279 | //! While these: |
280 | //! |
281 | //! ``` |
282 | //! println!("{}, `{name:.*}` has 3 fractional digits" , "Hello" , 3, name=1234.56); |
283 | //! println!("{}, `{name:.*}` has 3 characters" , "Hello" , 3, name="1234.56" ); |
284 | //! println!("{}, `{name:>8.*}` has 3 right-aligned characters" , "Hello" , 3, name="1234.56" ); |
285 | //! ``` |
286 | //! |
287 | //! print three significantly different things: |
288 | //! |
289 | //! ```text |
290 | //! Hello, `1234.560` has 3 fractional digits |
291 | //! Hello, `123` has 3 characters |
292 | //! Hello, ` 123` has 3 right-aligned characters |
293 | //! ``` |
294 | //! |
295 | //! When truncating these values, Rust uses [round half-to-even](https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even), |
296 | //! which is the default rounding mode in IEEE 754. |
297 | //! For example, |
298 | //! |
299 | //! ``` |
300 | //! print!("{0:.1$e}" , 12345, 3); |
301 | //! print!("{0:.1$e}" , 12355, 3); |
302 | //! ``` |
303 | //! |
304 | //! Would return: |
305 | //! |
306 | //! ```text |
307 | //! 1.234e4 |
308 | //! 1.236e4 |
309 | //! ``` |
310 | //! |
311 | //! ## Localization |
312 | //! |
313 | //! In some programming languages, the behavior of string formatting functions |
314 | //! depends on the operating system's locale setting. The format functions |
315 | //! provided by Rust's standard library do not have any concept of locale and |
316 | //! will produce the same results on all systems regardless of user |
317 | //! configuration. |
318 | //! |
319 | //! For example, the following code will always print `1.5` even if the system |
320 | //! locale uses a decimal separator other than a dot. |
321 | //! |
322 | //! ``` |
323 | //! println!("The value is {}" , 1.5); |
324 | //! ``` |
325 | //! |
326 | //! # Escaping |
327 | //! |
328 | //! The literal characters `{` and `}` may be included in a string by preceding |
329 | //! them with the same character. For example, the `{` character is escaped with |
330 | //! `{{` and the `}` character is escaped with `}}`. |
331 | //! |
332 | //! ``` |
333 | //! assert_eq!(format!("Hello {{}}" ), "Hello {}" ); |
334 | //! assert_eq!(format!("{{ Hello" ), "{ Hello" ); |
335 | //! ``` |
336 | //! |
337 | //! # Syntax |
338 | //! |
339 | //! To summarize, here you can find the full grammar of format strings. |
340 | //! The syntax for the formatting language used is drawn from other languages, |
341 | //! so it should not be too alien. Arguments are formatted with Python-like |
342 | //! syntax, meaning that arguments are surrounded by `{}` instead of the C-like |
343 | //! `%`. The actual grammar for the formatting syntax is: |
344 | //! |
345 | //! ```text |
346 | //! format_string := text [ maybe_format text ] * |
347 | //! maybe_format := '{' '{' | '}' '}' | format |
348 | //! format := '{' [ argument ] [ ':' format_spec ] [ ws ] * '}' |
349 | //! argument := integer | identifier |
350 | //! |
351 | //! format_spec := [[fill]align][sign]['#']['0'][width]['.' precision]type |
352 | //! fill := character |
353 | //! align := '<' | '^' | '>' |
354 | //! sign := '+' | '-' |
355 | //! width := count |
356 | //! precision := count | '*' |
357 | //! type := '' | '?' | 'x?' | 'X?' | identifier |
358 | //! count := parameter | integer |
359 | //! parameter := argument '$' |
360 | //! ``` |
361 | //! In the above grammar, |
362 | //! - `text` must not contain any `'{'` or `'}'` characters, |
363 | //! - `ws` is any character for which [`char::is_whitespace`] returns `true`, has no semantic |
364 | //! meaning and is completely optional, |
365 | //! - `integer` is a decimal integer that may contain leading zeroes and must fit into an `usize` and |
366 | //! - `identifier` is an `IDENTIFIER_OR_KEYWORD` (not an `IDENTIFIER`) as defined by the [Rust language reference](https://doc.rust-lang.org/reference/identifiers.html). |
367 | //! |
368 | //! # Formatting traits |
369 | //! |
370 | //! When requesting that an argument be formatted with a particular type, you |
371 | //! are actually requesting that an argument ascribes to a particular trait. |
372 | //! This allows multiple actual types to be formatted via `{:x}` (like [`i8`] as |
373 | //! well as [`isize`]). The current mapping of types to traits is: |
374 | //! |
375 | //! * *nothing* ⇒ [`Display`] |
376 | //! * `?` ⇒ [`Debug`] |
377 | //! * `x?` ⇒ [`Debug`] with lower-case hexadecimal integers |
378 | //! * `X?` ⇒ [`Debug`] with upper-case hexadecimal integers |
379 | //! * `o` ⇒ [`Octal`] |
380 | //! * `x` ⇒ [`LowerHex`] |
381 | //! * `X` ⇒ [`UpperHex`] |
382 | //! * `p` ⇒ [`Pointer`] |
383 | //! * `b` ⇒ [`Binary`] |
384 | //! * `e` ⇒ [`LowerExp`] |
385 | //! * `E` ⇒ [`UpperExp`] |
386 | //! |
387 | //! What this means is that any type of argument which implements the |
388 | //! [`fmt::Binary`][`Binary`] trait can then be formatted with `{:b}`. Implementations |
389 | //! are provided for these traits for a number of primitive types by the |
390 | //! standard library as well. If no format is specified (as in `{}` or `{:6}`), |
391 | //! then the format trait used is the [`Display`] trait. |
392 | //! |
393 | //! When implementing a format trait for your own type, you will have to |
394 | //! implement a method of the signature: |
395 | //! |
396 | //! ``` |
397 | //! # #![allow(dead_code)] |
398 | //! # use std::fmt; |
399 | //! # struct Foo; // our custom type |
400 | //! # impl fmt::Display for Foo { |
401 | //! fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
402 | //! # write!(f, "testing, testing" ) |
403 | //! # } } |
404 | //! ``` |
405 | //! |
406 | //! Your type will be passed as `self` by-reference, and then the function |
407 | //! should emit output into the Formatter `f` which implements `fmt::Write`. It is up to each |
408 | //! format trait implementation to correctly adhere to the requested formatting parameters. |
409 | //! The values of these parameters can be accessed with methods of the |
410 | //! [`Formatter`] struct. In order to help with this, the [`Formatter`] struct also |
411 | //! provides some helper methods. |
412 | //! |
413 | //! Additionally, the return value of this function is [`fmt::Result`] which is a |
414 | //! type alias of <code>[Result]<(), [std::fmt::Error]></code>. Formatting implementations |
415 | //! should ensure that they propagate errors from the [`Formatter`] (e.g., when |
416 | //! calling [`write!`]). However, they should never return errors spuriously. That |
417 | //! is, a formatting implementation must and may only return an error if the |
418 | //! passed-in [`Formatter`] returns an error. This is because, contrary to what |
419 | //! the function signature might suggest, string formatting is an infallible |
420 | //! operation. This function only returns a [`Result`] because writing to the |
421 | //! underlying stream might fail and it must provide a way to propagate the fact |
422 | //! that an error has occurred back up the stack. |
423 | //! |
424 | //! An example of implementing the formatting traits would look |
425 | //! like: |
426 | //! |
427 | //! ``` |
428 | //! use std::fmt; |
429 | //! |
430 | //! #[derive(Debug)] |
431 | //! struct Vector2D { |
432 | //! x: isize, |
433 | //! y: isize, |
434 | //! } |
435 | //! |
436 | //! impl fmt::Display for Vector2D { |
437 | //! fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
438 | //! // The `f` value implements the `Write` trait, which is what the |
439 | //! // write! macro is expecting. Note that this formatting ignores the |
440 | //! // various flags provided to format strings. |
441 | //! write!(f, "({}, {})" , self.x, self.y) |
442 | //! } |
443 | //! } |
444 | //! |
445 | //! // Different traits allow different forms of output of a type. The meaning |
446 | //! // of this format is to print the magnitude of a vector. |
447 | //! impl fmt::Binary for Vector2D { |
448 | //! fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
449 | //! let magnitude = (self.x * self.x + self.y * self.y) as f64; |
450 | //! let magnitude = magnitude.sqrt(); |
451 | //! |
452 | //! // Respect the formatting flags by using the helper method |
453 | //! // `pad_integral` on the Formatter object. See the method |
454 | //! // documentation for details, and the function `pad` can be used |
455 | //! // to pad strings. |
456 | //! let decimals = f.precision().unwrap_or(3); |
457 | //! let string = format!("{magnitude:.decimals$}" ); |
458 | //! f.pad_integral(true, "" , &string) |
459 | //! } |
460 | //! } |
461 | //! |
462 | //! fn main() { |
463 | //! let myvector = Vector2D { x: 3, y: 4 }; |
464 | //! |
465 | //! println!("{myvector}" ); // => "(3, 4)" |
466 | //! println!("{myvector:?}" ); // => "Vector2D {x: 3, y:4}" |
467 | //! println!("{myvector:10.3b}" ); // => " 5.000" |
468 | //! } |
469 | //! ``` |
470 | //! |
471 | //! ### `fmt::Display` vs `fmt::Debug` |
472 | //! |
473 | //! These two formatting traits have distinct purposes: |
474 | //! |
475 | //! - [`fmt::Display`][`Display`] implementations assert that the type can be faithfully |
476 | //! represented as a UTF-8 string at all times. It is **not** expected that |
477 | //! all types implement the [`Display`] trait. |
478 | //! - [`fmt::Debug`][`Debug`] implementations should be implemented for **all** public types. |
479 | //! Output will typically represent the internal state as faithfully as possible. |
480 | //! The purpose of the [`Debug`] trait is to facilitate debugging Rust code. In |
481 | //! most cases, using `#[derive(Debug)]` is sufficient and recommended. |
482 | //! |
483 | //! Some examples of the output from both traits: |
484 | //! |
485 | //! ``` |
486 | //! assert_eq!(format!("{} {:?}" , 3, 4), "3 4" ); |
487 | //! assert_eq!(format!("{} {:?}" , 'a' , 'b' ), "a 'b'" ); |
488 | //! assert_eq!(format!("{} {:?}" , "foo \n" , "bar \n" ), "foo \n \"bar \\n \"" ); |
489 | //! ``` |
490 | //! |
491 | //! # Related macros |
492 | //! |
493 | //! There are a number of related macros in the [`format!`] family. The ones that |
494 | //! are currently implemented are: |
495 | //! |
496 | //! ```ignore (only-for-syntax-highlight) |
497 | //! format! // described above |
498 | //! write! // first argument is either a &mut io::Write or a &mut fmt::Write, the destination |
499 | //! writeln! // same as write but appends a newline |
500 | //! print! // the format string is printed to the standard output |
501 | //! println! // same as print but appends a newline |
502 | //! eprint! // the format string is printed to the standard error |
503 | //! eprintln! // same as eprint but appends a newline |
504 | //! format_args! // described below. |
505 | //! ``` |
506 | //! |
507 | //! ### `write!` |
508 | //! |
509 | //! [`write!`] and [`writeln!`] are two macros which are used to emit the format string |
510 | //! to a specified stream. This is used to prevent intermediate allocations of |
511 | //! format strings and instead directly write the output. Under the hood, this |
512 | //! function is actually invoking the [`write_fmt`] function defined on the |
513 | //! [`std::io::Write`] and the [`std::fmt::Write`] trait. Example usage is: |
514 | //! |
515 | //! ``` |
516 | //! # #![allow(unused_must_use)] |
517 | //! use std::io::Write; |
518 | //! let mut w = Vec::new(); |
519 | //! write!(&mut w, "Hello {}!" , "world" ); |
520 | //! ``` |
521 | //! |
522 | //! ### `print!` |
523 | //! |
524 | //! This and [`println!`] emit their output to stdout. Similarly to the [`write!`] |
525 | //! macro, the goal of these macros is to avoid intermediate allocations when |
526 | //! printing output. Example usage is: |
527 | //! |
528 | //! ``` |
529 | //! print!("Hello {}!" , "world" ); |
530 | //! println!("I have a newline {}" , "character at the end" ); |
531 | //! ``` |
532 | //! ### `eprint!` |
533 | //! |
534 | //! The [`eprint!`] and [`eprintln!`] macros are identical to |
535 | //! [`print!`] and [`println!`], respectively, except they emit their |
536 | //! output to stderr. |
537 | //! |
538 | //! ### `format_args!` |
539 | //! |
540 | //! [`format_args!`] is a curious macro used to safely pass around |
541 | //! an opaque object describing the format string. This object |
542 | //! does not require any heap allocations to create, and it only |
543 | //! references information on the stack. Under the hood, all of |
544 | //! the related macros are implemented in terms of this. First |
545 | //! off, some example usage is: |
546 | //! |
547 | //! ``` |
548 | //! # #![allow(unused_must_use)] |
549 | //! use std::fmt; |
550 | //! use std::io::{self, Write}; |
551 | //! |
552 | //! let mut some_writer = io::stdout(); |
553 | //! write!(&mut some_writer, "{}" , format_args!("print with a {}" , "macro" )); |
554 | //! |
555 | //! fn my_fmt_fn(args: fmt::Arguments<'_>) { |
556 | //! write!(&mut io::stdout(), "{args}" ); |
557 | //! } |
558 | //! my_fmt_fn(format_args!(", or a {} too" , "function" )); |
559 | //! ``` |
560 | //! |
561 | //! The result of the [`format_args!`] macro is a value of type [`fmt::Arguments`]. |
562 | //! This structure can then be passed to the [`write`] and [`format`] functions |
563 | //! inside this module in order to process the format string. |
564 | //! The goal of this macro is to even further prevent intermediate allocations |
565 | //! when dealing with formatting strings. |
566 | //! |
567 | //! For example, a logging library could use the standard formatting syntax, but |
568 | //! it would internally pass around this structure until it has been determined |
569 | //! where output should go to. |
570 | //! |
571 | //! [`fmt::Result`]: Result "fmt::Result" |
572 | //! [Result]: core::result::Result "std::result::Result" |
573 | //! [std::fmt::Error]: Error "fmt::Error" |
574 | //! [`write`]: write() "fmt::write" |
575 | //! [`to_string`]: crate::string::ToString::to_string "ToString::to_string" |
576 | //! [`write_fmt`]: ../../std/io/trait.Write.html#method.write_fmt |
577 | //! [`std::io::Write`]: ../../std/io/trait.Write.html |
578 | //! [`std::fmt::Write`]: ../../std/fmt/trait.Write.html |
579 | //! [`print!`]: ../../std/macro.print.html "print!" |
580 | //! [`println!`]: ../../std/macro.println.html "println!" |
581 | //! [`eprint!`]: ../../std/macro.eprint.html "eprint!" |
582 | //! [`eprintln!`]: ../../std/macro.eprintln.html "eprintln!" |
583 | //! [`format_args!`]: ../../std/macro.format_args.html "format_args!" |
584 | //! [`fmt::Arguments`]: Arguments "fmt::Arguments" |
585 | //! [`format`]: format() "fmt::format" |
586 | |
587 | #![stable (feature = "rust1" , since = "1.0.0" )] |
588 | |
589 | #[stable (feature = "fmt_flags_align" , since = "1.28.0" )] |
590 | pub use core::fmt::Alignment; |
591 | #[stable (feature = "rust1" , since = "1.0.0" )] |
592 | pub use core::fmt::Error; |
593 | #[stable (feature = "rust1" , since = "1.0.0" )] |
594 | pub use core::fmt::{Arguments, write}; |
595 | #[stable (feature = "rust1" , since = "1.0.0" )] |
596 | pub use core::fmt::{Binary, Octal}; |
597 | #[stable (feature = "rust1" , since = "1.0.0" )] |
598 | pub use core::fmt::{Debug, Display}; |
599 | #[unstable (feature = "formatting_options" , issue = "118117" )] |
600 | pub use core::fmt::{DebugAsHex, FormattingOptions, Sign}; |
601 | #[stable (feature = "rust1" , since = "1.0.0" )] |
602 | pub use core::fmt::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple}; |
603 | #[stable (feature = "rust1" , since = "1.0.0" )] |
604 | pub use core::fmt::{Formatter, Result, Write}; |
605 | #[unstable (feature = "debug_closure_helpers" , issue = "117729" )] |
606 | pub use core::fmt::{FromFn, from_fn}; |
607 | #[stable (feature = "rust1" , since = "1.0.0" )] |
608 | pub use core::fmt::{LowerExp, UpperExp}; |
609 | #[stable (feature = "rust1" , since = "1.0.0" )] |
610 | pub use core::fmt::{LowerHex, Pointer, UpperHex}; |
611 | |
612 | #[cfg (not(no_global_oom_handling))] |
613 | use crate::string; |
614 | |
615 | /// Takes an [`Arguments`] struct and returns the resulting formatted string. |
616 | /// |
617 | /// The [`Arguments`] instance can be created with the [`format_args!`] macro. |
618 | /// |
619 | /// # Examples |
620 | /// |
621 | /// Basic usage: |
622 | /// |
623 | /// ``` |
624 | /// use std::fmt; |
625 | /// |
626 | /// let s = fmt::format(format_args!("Hello, {}!" , "world" )); |
627 | /// assert_eq!(s, "Hello, world!" ); |
628 | /// ``` |
629 | /// |
630 | /// Please note that using [`format!`] might be preferable. |
631 | /// Example: |
632 | /// |
633 | /// ``` |
634 | /// let s = format!("Hello, {}!" , "world" ); |
635 | /// assert_eq!(s, "Hello, world!" ); |
636 | /// ``` |
637 | /// |
638 | /// [`format_args!`]: core::format_args |
639 | /// [`format!`]: crate::format |
640 | #[cfg (not(no_global_oom_handling))] |
641 | #[must_use ] |
642 | #[stable (feature = "rust1" , since = "1.0.0" )] |
643 | #[inline ] |
644 | pub fn format(args: Arguments<'_>) -> string::String { |
645 | fn format_inner(args: Arguments<'_>) -> string::String { |
646 | let capacity: usize = args.estimated_capacity(); |
647 | let mut output: String = string::String::with_capacity(capacity); |
648 | output |
649 | .write_fmt(args) |
650 | .expect(msg:"a formatting trait implementation returned an error when the underlying stream did not" ); |
651 | output |
652 | } |
653 | |
654 | args.as_str().map_or_else(|| format_inner(args), f:crate::borrow::ToOwned::to_owned) |
655 | } |
656 | |