| 
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