|
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 | | -//! ```rust |
| 57 | +//! ``` |
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. |
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 |
| 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 |
113 | 120 | //! invalid format string: |
114 | 121 | //! |
115 | 122 | //! ```text |
116 | 123 | //! {:.*} {0} |
117 | 124 | //! ``` |
118 | 125 | //! |
119 | | -//! ### Formatting traits |
| 126 | +//! ## Formatting traits |
120 | 127 | //! |
121 | 128 | //! When requesting that an argument be formatted with a particular type, you |
122 | 129 | //! are actually requesting that an argument ascribes to a particular trait. |
|
142 | 149 | //! When implementing a format trait for your own type, you will have to |
143 | 150 | //! implement a method of the signature: |
144 | 151 | //! |
145 | | -//! ```rust |
| 152 | +//! ``` |
146 | 153 | //! # use std::fmt; |
147 | 154 | //! # struct Foo; // our custom type |
148 | 155 | //! # impl fmt::Display for Foo { |
|
166 | 173 | //! An example of implementing the formatting traits would look |
167 | 174 | //! like: |
168 | 175 | //! |
169 | | -//! ```rust |
| 176 | +//! ``` |
170 | 177 | //! use std::fmt; |
171 | 178 | //! use std::f64; |
172 | 179 | //! use std::num::Float; |
|
211 | 218 | //! } |
212 | 219 | //! ``` |
213 | 220 | //! |
214 | | -//! #### fmt::Display vs fmt::Debug |
| 221 | +//! ### fmt::Display vs fmt::Debug |
215 | 222 | //! |
216 | 223 | //! These two formatting traits have distinct purposes: |
217 | 224 | //! |
|
231 | 238 | //! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\""); |
232 | 239 | //! ``` |
233 | 240 | //! |
234 | | -//! ### Related macros |
| 241 | +//! ## Related macros |
235 | 242 | //! |
236 | 243 | //! There are a number of related macros in the `format!` family. The ones that |
237 | 244 | //! are currently implemented are: |
|
245 | 252 | //! format_args! // described below. |
246 | 253 | //! ``` |
247 | 254 | //! |
248 | | -//! #### `write!` |
| 255 | +//! ### `write!` |
249 | 256 | //! |
250 | 257 | //! This and `writeln` are two macros which are used to emit the format string |
251 | 258 | //! to a specified stream. This is used to prevent intermediate allocations of |
252 | 259 | //! format strings and instead directly write the output. Under the hood, this |
253 | 260 | //! function is actually invoking the `write` function defined in this module. |
254 | 261 | //! Example usage is: |
255 | 262 | //! |
256 | | -//! ```rust |
| 263 | +//! ``` |
257 | 264 | //! # #![allow(unused_must_use)] |
258 | 265 | //! let mut w = Vec::new(); |
259 | 266 | //! write!(&mut w, "Hello {}!", "world"); |
260 | 267 | //! ``` |
261 | 268 | //! |
262 | | -//! #### `print!` |
| 269 | +//! ### `print!` |
263 | 270 | //! |
264 | 271 | //! This and `println` emit their output to stdout. Similarly to the `write!` |
265 | 272 | //! macro, the goal of these macros is to avoid intermediate allocations when |
266 | 273 | //! printing output. Example usage is: |
267 | 274 | //! |
268 | | -//! ```rust |
| 275 | +//! ``` |
269 | 276 | //! print!("Hello {}!", "world"); |
270 | 277 | //! println!("I have a newline {}", "character at the end"); |
271 | 278 | //! ``` |
272 | 279 | //! |
273 | | -//! #### `format_args!` |
| 280 | +//! ### `format_args!` |
| 281 | +//! |
274 | 282 | //! This is a curious macro which is used to safely pass around |
275 | 283 | //! an opaque object describing the format string. This object |
276 | 284 | //! does not require any heap allocations to create, and it only |
|
303 | 311 | //! it would internally pass around this structure until it has been determined |
304 | 312 | //! where output should go to. |
305 | 313 | //! |
306 | | -//! ## Syntax |
| 314 | +//! # Syntax |
307 | 315 | //! |
308 | 316 | //! The syntax for the formatting language used is drawn from other languages, |
309 | 317 | //! so it should not be too alien. Arguments are formatted with python-like |
|
326 | 334 | //! parameter := integer '$' |
327 | 335 | //! ``` |
328 | 336 | //! |
329 | | -//! ## Formatting Parameters |
| 337 | +//! # Formatting Parameters |
330 | 338 | //! |
331 | 339 | //! Each argument being formatted can be transformed by a number of formatting |
332 | 340 | //! parameters (corresponding to `format_spec` in the syntax above). These |
333 | 341 | //! parameters affect the string representation of what's being formatted. This |
334 | 342 | //! syntax draws heavily from Python's, so it may seem a bit familiar. |
335 | 343 | //! |
336 | | -//! ### Fill/Alignment |
| 344 | +//! ## Fill/Alignment |
337 | 345 | //! |
338 | 346 | //! The fill character is provided normally in conjunction with the `width` |
339 | 347 | //! parameter. This indicates that if the value being formatted is smaller than |
|
345 | 353 | //! * `^` - the argument is center-aligned in `width` columns |
346 | 354 | //! * `>` - the argument is right-aligned in `width` columns |
347 | 355 | //! |
348 | | -//! ### Sign/#/0 |
| 356 | +//! ## Sign/#/0 |
349 | 357 | //! |
350 | 358 | //! These can all be interpreted as flags for a particular formatter. |
351 | 359 | //! |
|
368 | 376 | //! same format would yield `-0000001` for the integer `-1`. Notice that |
369 | 377 | //! the negative version has one fewer zero than the positive version. |
370 | 378 | //! |
371 | | -//! ### Width |
| 379 | +//! ## Width |
372 | 380 | //! |
373 | 381 | //! This is a parameter for the "minimum width" that the format should take up. |
374 | 382 | //! If the value's string does not fill up this many characters, then the |
|
384 | 392 | //! parameters by using the `2$` syntax indicating that the second argument is a |
385 | 393 | //! `usize` specifying the width. |
386 | 394 | //! |
387 | | -//! ### Precision |
| 395 | +//! ## Precision |
388 | 396 | //! |
389 | 397 | //! For non-numeric types, this can be considered a "maximum width". If the |
390 | 398 | //! resulting string is longer than this width, then it is truncated down to |
|
395 | 403 | //! For floating-point types, this indicates how many digits after the decimal |
396 | 404 | //! point should be printed. |
397 | 405 | //! |
398 | | -//! ## Escaping |
| 406 | +//! # Escaping |
399 | 407 | //! |
400 | 408 | //! The literal characters `{` and `}` may be included in a string by preceding |
401 | 409 | //! them with the same character. For example, the `{` character is escaped with |
|
0 commit comments