|
16 | 16 | //! This macro is implemented in the compiler to emit calls to this module in |
17 | 17 | //! order to format arguments at runtime into strings and streams. |
18 | 18 | //! |
19 | | -//! # Usage |
| 19 | +//! ## Usage |
20 | 20 | //! |
21 | 21 | //! The `format!` macro is intended to be familiar to those coming from C's |
22 | 22 | //! printf/fprintf functions or Python's `str.format` function. In its current |
|
41 | 41 | //! will then parse the format string and determine if the list of arguments |
42 | 42 | //! provided is suitable to pass to this format string. |
43 | 43 | //! |
44 | | -//! ## Positional parameters |
| 44 | +//! ### Positional parameters |
45 | 45 | //! |
46 | 46 | //! Each formatting argument is allowed to specify which value argument it's |
47 | 47 | //! referencing, and if omitted it is assumed to be "the next argument". For |
|
54 | 54 | //! iterator over the argument. Each time a "next argument" specifier is seen, |
55 | 55 | //! the iterator advances. This leads to behavior like this: |
56 | 56 | //! |
57 | | -//! ``` |
| 57 | +//! ```rust |
58 | 58 | //! format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2" |
59 | 59 | //! ``` |
60 | 60 | //! |
|
68 | 68 | //! compile-time error. You may refer to the same argument more than once in the |
69 | 69 | //! format string, although it must always be referred to with the same type. |
70 | 70 | //! |
71 | | -//! ## Named parameters |
| 71 | +//! ### Named parameters |
72 | 72 | //! |
73 | 73 | //! Rust itself does not have a Python-like equivalent of named parameters to a |
74 | 74 | //! function, but the `format!` macro is a syntax extension which allows it to |
|
91 | 91 | //! arguments which have names. Like with positional parameters, it is illegal |
92 | 92 | //! to provide named parameters that are unused by the format string. |
93 | 93 | //! |
94 | | -//! ## Argument types |
| 94 | +//! ### Argument types |
95 | 95 | //! |
96 | 96 | //! Each argument's type is dictated by the format string. It is a requirement |
97 | 97 | //! that every argument is only ever referred to by one type. For example, this |
|
105 | 105 | //! hexadecimal as well as an |
106 | 106 | //! octal. |
107 | 107 | //! |
108 | | -//! There are various parameters which do require a particular type, however. Namely, the `{:.*}` |
109 | | -//! syntax, which sets the number of numbers after the decimal in floating-point types: |
110 | | -//! |
111 | | -//! ``` |
112 | | -//! let formatted_number = format!("{:.*}", 2, 1.234567); |
113 | | -//! |
114 | | -//! assert_eq!("1.23", formatted_number) |
115 | | -//! ``` |
116 | | -//! |
117 | | -//! If this syntax is used, then the number of characters to print precedes the actual object being |
118 | | -//! formatted, and the number of characters must have the type `usize`. Although a `usize` can be |
119 | | -//! printed with `{}`, it is illegal to reference an argument as such. For example this is another |
| 108 | +//! There are various parameters which do require a particular type, however. |
| 109 | +//! Namely if the syntax `{:.*}` is used, then the number of characters to print |
| 110 | +//! precedes the actual object being formatted, and the number of characters |
| 111 | +//! must have the type `usize`. Although a `usize` can be printed with `{}`, it is |
| 112 | +//! illegal to reference an argument as such. For example this is another |
120 | 113 | //! invalid format string: |
121 | 114 | //! |
122 | 115 | //! ```text |
123 | 116 | //! {:.*} {0} |
124 | 117 | //! ``` |
125 | 118 | //! |
126 | | -//! ## Formatting traits |
| 119 | +//! ### Formatting traits |
127 | 120 | //! |
128 | 121 | //! When requesting that an argument be formatted with a particular type, you |
129 | 122 | //! are actually requesting that an argument ascribes to a particular trait. |
|
149 | 142 | //! When implementing a format trait for your own type, you will have to |
150 | 143 | //! implement a method of the signature: |
151 | 144 | //! |
152 | | -//! ``` |
| 145 | +//! ```rust |
153 | 146 | //! # use std::fmt; |
154 | 147 | //! # struct Foo; // our custom type |
155 | 148 | //! # impl fmt::Display for Foo { |
|
173 | 166 | //! An example of implementing the formatting traits would look |
174 | 167 | //! like: |
175 | 168 | //! |
176 | | -//! ``` |
| 169 | +//! ```rust |
177 | 170 | //! use std::fmt; |
178 | 171 | //! use std::f64; |
179 | 172 | //! use std::num::Float; |
|
218 | 211 | //! } |
219 | 212 | //! ``` |
220 | 213 | //! |
221 | | -//! ### fmt::Display vs fmt::Debug |
| 214 | +//! #### fmt::Display vs fmt::Debug |
222 | 215 | //! |
223 | 216 | //! These two formatting traits have distinct purposes: |
224 | 217 | //! |
|
238 | 231 | //! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\""); |
239 | 232 | //! ``` |
240 | 233 | //! |
241 | | -//! ## Related macros |
| 234 | +//! ### Related macros |
242 | 235 | //! |
243 | 236 | //! There are a number of related macros in the `format!` family. The ones that |
244 | 237 | //! are currently implemented are: |
|
252 | 245 | //! format_args! // described below. |
253 | 246 | //! ``` |
254 | 247 | //! |
255 | | -//! ### `write!` |
| 248 | +//! #### `write!` |
256 | 249 | //! |
257 | 250 | //! This and `writeln` are two macros which are used to emit the format string |
258 | 251 | //! to a specified stream. This is used to prevent intermediate allocations of |
259 | 252 | //! format strings and instead directly write the output. Under the hood, this |
260 | 253 | //! function is actually invoking the `write` function defined in this module. |
261 | 254 | //! Example usage is: |
262 | 255 | //! |
263 | | -//! ``` |
| 256 | +//! ```rust |
264 | 257 | //! # #![allow(unused_must_use)] |
265 | 258 | //! let mut w = Vec::new(); |
266 | 259 | //! write!(&mut w, "Hello {}!", "world"); |
267 | 260 | //! ``` |
268 | 261 | //! |
269 | | -//! ### `print!` |
| 262 | +//! #### `print!` |
270 | 263 | //! |
271 | 264 | //! This and `println` emit their output to stdout. Similarly to the `write!` |
272 | 265 | //! macro, the goal of these macros is to avoid intermediate allocations when |
273 | 266 | //! printing output. Example usage is: |
274 | 267 | //! |
275 | | -//! ``` |
| 268 | +//! ```rust |
276 | 269 | //! print!("Hello {}!", "world"); |
277 | 270 | //! println!("I have a newline {}", "character at the end"); |
278 | 271 | //! ``` |
279 | 272 | //! |
280 | | -//! ### `format_args!` |
281 | | -//! |
| 273 | +//! #### `format_args!` |
282 | 274 | //! This is a curious macro which is used to safely pass around |
283 | 275 | //! an opaque object describing the format string. This object |
284 | 276 | //! does not require any heap allocations to create, and it only |
|
311 | 303 | //! it would internally pass around this structure until it has been determined |
312 | 304 | //! where output should go to. |
313 | 305 | //! |
314 | | -//! # Syntax |
| 306 | +//! ## Syntax |
315 | 307 | //! |
316 | 308 | //! The syntax for the formatting language used is drawn from other languages, |
317 | 309 | //! so it should not be too alien. Arguments are formatted with python-like |
|
334 | 326 | //! parameter := integer '$' |
335 | 327 | //! ``` |
336 | 328 | //! |
337 | | -//! # Formatting Parameters |
| 329 | +//! ## Formatting Parameters |
338 | 330 | //! |
339 | 331 | //! Each argument being formatted can be transformed by a number of formatting |
340 | 332 | //! parameters (corresponding to `format_spec` in the syntax above). These |
341 | 333 | //! parameters affect the string representation of what's being formatted. This |
342 | 334 | //! syntax draws heavily from Python's, so it may seem a bit familiar. |
343 | 335 | //! |
344 | | -//! ## Fill/Alignment |
| 336 | +//! ### Fill/Alignment |
345 | 337 | //! |
346 | 338 | //! The fill character is provided normally in conjunction with the `width` |
347 | 339 | //! parameter. This indicates that if the value being formatted is smaller than |
|
353 | 345 | //! * `^` - the argument is center-aligned in `width` columns |
354 | 346 | //! * `>` - the argument is right-aligned in `width` columns |
355 | 347 | //! |
356 | | -//! ## Sign/#/0 |
| 348 | +//! ### Sign/#/0 |
357 | 349 | //! |
358 | 350 | //! These can all be interpreted as flags for a particular formatter. |
359 | 351 | //! |
|
376 | 368 | //! same format would yield `-0000001` for the integer `-1`. Notice that |
377 | 369 | //! the negative version has one fewer zero than the positive version. |
378 | 370 | //! |
379 | | -//! ## Width |
| 371 | +//! ### Width |
380 | 372 | //! |
381 | 373 | //! This is a parameter for the "minimum width" that the format should take up. |
382 | 374 | //! If the value's string does not fill up this many characters, then the |
|
392 | 384 | //! parameters by using the `2$` syntax indicating that the second argument is a |
393 | 385 | //! `usize` specifying the width. |
394 | 386 | //! |
395 | | -//! ## Precision |
| 387 | +//! ### Precision |
396 | 388 | //! |
397 | 389 | //! For non-numeric types, this can be considered a "maximum width". If the |
398 | 390 | //! resulting string is longer than this width, then it is truncated down to |
|
403 | 395 | //! For floating-point types, this indicates how many digits after the decimal |
404 | 396 | //! point should be printed. |
405 | 397 | //! |
406 | | -//! # Escaping |
| 398 | +//! ## Escaping |
407 | 399 | //! |
408 | 400 | //! The literal characters `{` and `}` may be included in a string by preceding |
409 | 401 | //! them with the same character. For example, the `{` character is escaped with |
|
0 commit comments