|
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