|  | 
| 86 | 86 | //! parameters (corresponding to `format_spec` in the syntax above). These | 
| 87 | 87 | //! parameters affect the string representation of what's being formatted. | 
| 88 | 88 | //! | 
|  | 89 | +//! ## Width | 
|  | 90 | +//! | 
|  | 91 | +//! ``` | 
|  | 92 | +//! // All of these print "Hello x    !" | 
|  | 93 | +//! println!("Hello {:5}!", "x"); | 
|  | 94 | +//! println!("Hello {:1$}!", "x", 5); | 
|  | 95 | +//! println!("Hello {1:0$}!", 5, "x"); | 
|  | 96 | +//! println!("Hello {:width$}!", "x", width = 5); | 
|  | 97 | +//! ``` | 
|  | 98 | +//! | 
|  | 99 | +//! This is a parameter for the "minimum width" that the format should take up. | 
|  | 100 | +//! If the value's string does not fill up this many characters, then the | 
|  | 101 | +//! padding specified by fill/alignment will be used to take up the required | 
|  | 102 | +//! space (see below). | 
|  | 103 | +//! | 
|  | 104 | +//! The value for the width can also be provided as a [`usize`] in the list of | 
|  | 105 | +//! parameters by adding a postfix `$`, indicating that the second argument is | 
|  | 106 | +//! a [`usize`] specifying the width. | 
|  | 107 | +//! | 
|  | 108 | +//! Referring to an argument with the dollar syntax does not affect the "next | 
|  | 109 | +//! argument" counter, so it's usually a good idea to refer to arguments by | 
|  | 110 | +//! position, or use named arguments. | 
|  | 111 | +//! | 
| 89 | 112 | //! ## Fill/Alignment | 
| 90 | 113 | //! | 
| 91 |  | -//! The fill character is provided normally in conjunction with the | 
| 92 |  | -//! [`width`](#width) | 
| 93 |  | -//! parameter. This indicates that if the value being formatted is smaller than | 
| 94 |  | -//! `width` some extra characters will be printed around it. The extra | 
| 95 |  | -//! characters are specified by `fill`, and the alignment can be one of the | 
| 96 |  | -//! following options: | 
|  | 114 | +//! ``` | 
|  | 115 | +//! assert_eq!(format!("Hello {:<5}!", "x"),  "Hello x    !"); | 
|  | 116 | +//! assert_eq!(format!("Hello {:-<5}!", "x"), "Hello x----!"); | 
|  | 117 | +//! assert_eq!(format!("Hello {:^5}!", "x"),  "Hello   x  !"); | 
|  | 118 | +//! assert_eq!(format!("Hello {:>5}!", "x"),  "Hello     x!"); | 
|  | 119 | +//! ``` | 
| 97 | 120 | //! | 
| 98 |  | -//! * `<` - the argument is left-aligned in `width` columns | 
| 99 |  | -//! * `^` - the argument is center-aligned in `width` columns | 
| 100 |  | -//! * `>` - the argument is right-aligned in `width` columns | 
|  | 121 | +//! The optional fill character and alignment is provided normally in conjunction with the | 
|  | 122 | +//! [`width`](#width) parameter. It must be defined before `width`, right after the `:`. | 
|  | 123 | +//! This indicates that if the value being formatted is smaller than | 
|  | 124 | +//! `width` some extra characters will be printed around it. | 
|  | 125 | +//! Filling comes in the following variants for different alignments: | 
|  | 126 | +//! | 
|  | 127 | +//! * `[fill]<` - the argument is left-aligned in `width` columns | 
|  | 128 | +//! * `[fill]^` - the argument is center-aligned in `width` columns | 
|  | 129 | +//! * `[fill]>` - the argument is right-aligned in `width` columns | 
|  | 130 | +//! | 
|  | 131 | +//! The default [fill/alignment](#fillalignment) for non-numerics is a space and | 
|  | 132 | +//! left-aligned. The | 
|  | 133 | +//! defaults for numeric formatters is also a space but with right-alignment. If | 
|  | 134 | +//! the `0` flag (see below) is specified for numerics, then the implicit fill character is | 
|  | 135 | +//! `0`. | 
| 101 | 136 | //! | 
| 102 | 137 | //! Note that alignment may not be implemented by some types. In particular, it | 
| 103 | 138 | //! is not generally implemented for the `Debug` trait.  A good way to ensure | 
| 104 |  | -//! padding is applied is to format your input, then use this resulting string | 
| 105 |  | -//! to pad your output. | 
|  | 139 | +//! padding is applied is to format your input, then pad this resulting string | 
|  | 140 | +//! to obtain your output: | 
|  | 141 | +//! | 
|  | 142 | +//! ``` | 
|  | 143 | +//! println!("Hello {:^15}!", format!("{:?}", Some("hi"))); // => "Hello   Some("hi")   !" | 
|  | 144 | +//! ``` | 
| 106 | 145 | //! | 
| 107 | 146 | //! ## Sign/`#`/`0` | 
| 108 | 147 | //! | 
| 109 |  | -//! These can all be interpreted as flags for a particular formatter. | 
|  | 148 | +//! ``` | 
|  | 149 | +//! assert_eq!(format!("Hello {:+}!", 5), "Hello +5!"); | 
|  | 150 | +//! assert_eq!(format!("{:#x}!", 27), "0x1b!"); | 
|  | 151 | +//! assert_eq!(format!("Hello {:05}!", 5),  "Hello 00005!"); | 
|  | 152 | +//! assert_eq!(format!("Hello {:05}!", -5), "Hello -0005!"); | 
|  | 153 | +//! assert_eq!(format!("{:#010x}!", 27), "0x0000001b!"); | 
|  | 154 | +//! ``` | 
|  | 155 | +//! | 
|  | 156 | +//! These are all flags altering the behavior of the formatter. | 
| 110 | 157 | //! | 
| 111 | 158 | //! * `+` - This is intended for numeric types and indicates that the sign | 
| 112 | 159 | //!         should always be printed. Positive signs are never printed by | 
|  | 
| 121 | 168 | //!     * `#X` - precedes the argument with a `0x` | 
| 122 | 169 | //!     * `#b` - precedes the argument with a `0b` | 
| 123 | 170 | //!     * `#o` - precedes the argument with a `0o` | 
| 124 |  | -//! * `0` - This is used to indicate for integer formats that the padding should | 
|  | 171 | +//! * `0` - This is used to indicate for integer formats that the padding to `width` should | 
| 125 | 172 | //!         both be done with a `0` character as well as be sign-aware. A format | 
| 126 | 173 | //!         like `{:08}` would yield `00000001` for the integer `1`, while the | 
| 127 | 174 | //!         same format would yield `-0000001` for the integer `-1`. Notice that | 
| 128 | 175 | //!         the negative version has one fewer zero than the positive version. | 
| 129 | 176 | //!         Note that padding zeroes are always placed after the sign (if any) | 
| 130 | 177 | //!         and before the digits. When used together with the `#` flag, a similar | 
| 131 | 178 | //!         rule applies: padding zeroes are inserted after the prefix but before | 
| 132 |  | -//!         the digits. | 
| 133 |  | -//! | 
| 134 |  | -//! ## Width | 
| 135 |  | -//! | 
| 136 |  | -//! This is a parameter for the "minimum width" that the format should take up. | 
| 137 |  | -//! If the value's string does not fill up this many characters, then the | 
| 138 |  | -//! padding specified by fill/alignment will be used to take up the required | 
| 139 |  | -//! space. | 
| 140 |  | -//! | 
| 141 |  | -//! The default [fill/alignment](#fillalignment) for non-numerics is a space and | 
| 142 |  | -//! left-aligned. The | 
| 143 |  | -//! defaults for numeric formatters is also a space but with right-alignment. If | 
| 144 |  | -//! the `0` flag is specified for numerics, then the implicit fill character is | 
| 145 |  | -//! `0`. | 
| 146 |  | -//! | 
| 147 |  | -//! The value for the width can also be provided as a [`usize`] in the list of | 
| 148 |  | -//! parameters by using the dollar syntax indicating that the second argument is | 
| 149 |  | -//! a [`usize`] specifying the width, for example: | 
| 150 |  | -//! | 
| 151 |  | -//! ``` | 
| 152 |  | -//! // All of these print "Hello x    !" | 
| 153 |  | -//! println!("Hello {:5}!", "x"); | 
| 154 |  | -//! println!("Hello {:1$}!", "x", 5); | 
| 155 |  | -//! println!("Hello {1:0$}!", 5, "x"); | 
| 156 |  | -//! println!("Hello {:width$}!", "x", width = 5); | 
| 157 |  | -//! ``` | 
| 158 |  | -//! | 
| 159 |  | -//! Referring to an argument with the dollar syntax does not affect the "next | 
| 160 |  | -//! argument" counter, so it's usually a good idea to refer to arguments by | 
| 161 |  | -//! position, or use named arguments. | 
|  | 179 | +//!         the digits. The prefix is included in the total width. | 
| 162 | 180 | //! | 
| 163 | 181 | //! ## Precision | 
| 164 | 182 | //! | 
|  | 
| 235 | 253 | //! them with the same character. For example, the `{` character is escaped with | 
| 236 | 254 | //! `{{` and the `}` character is escaped with `}}`. | 
| 237 | 255 | //! | 
|  | 256 | +//! ``` | 
|  | 257 | +//! assert_eq!(format!("Hello {{}}"), "Hello {}"); | 
|  | 258 | +//! assert_eq!(format!("{{ Hello"), "{ Hello"); | 
|  | 259 | +//! ``` | 
|  | 260 | +//! | 
| 238 | 261 | //! # Syntax | 
| 239 | 262 | //! | 
| 240 |  | -//! To summarize, you can find the full grammar of format strings. | 
|  | 263 | +//! To summarize, here you can find the full grammar of format strings. | 
| 241 | 264 | //! The syntax for the formatting language used is drawn from other languages, | 
| 242 | 265 | //! so it should not be too alien. Arguments are formatted with Python-like | 
| 243 | 266 | //! syntax, meaning that arguments are surrounded by `{}` instead of the C-like | 
|  | 
0 commit comments