]>
Commit | Line | Data |
---|---|---|
85aaf69f | 1 | // Copyright 2013-2015 The Rust Project Developers. See the COPYRIGHT |
1a4d82fc JJ |
2 | // file at the top-level directory of this distribution and at |
3 | // http://rust-lang.org/COPYRIGHT. | |
4 | // | |
5 | // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or | |
6 | // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license | |
7 | // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your | |
8 | // option. This file may not be copied, modified, or distributed | |
9 | // except according to those terms. | |
1a4d82fc JJ |
10 | |
11 | //! Utilities for formatting and printing strings | |
12 | //! | |
13 | //! This module contains the runtime support for the `format!` syntax extension. | |
14 | //! This macro is implemented in the compiler to emit calls to this module in | |
15 | //! order to format arguments at runtime into strings and streams. | |
16 | //! | |
c34b1796 | 17 | //! # Usage |
1a4d82fc JJ |
18 | //! |
19 | //! The `format!` macro is intended to be familiar to those coming from C's | |
20 | //! printf/fprintf functions or Python's `str.format` function. In its current | |
21 | //! revision, the `format!` macro returns a `String` type which is the result of | |
22 | //! the formatting. In the future it will also be able to pass in a stream to | |
23 | //! format arguments directly while performing minimal allocations. | |
24 | //! | |
25 | //! Some examples of the `format!` extension are: | |
26 | //! | |
85aaf69f SL |
27 | //! ``` |
28 | //! format!("Hello"); // => "Hello" | |
29 | //! format!("Hello, {}!", "world"); // => "Hello, world!" | |
30 | //! format!("The number is {}", 1); // => "The number is 1" | |
31 | //! format!("{:?}", (3, 4)); // => "(3, 4)" | |
32 | //! format!("{value}", value=4); // => "4" | |
33 | //! format!("{} {}", 1, 2); // => "1 2" | |
1a4d82fc JJ |
34 | //! ``` |
35 | //! | |
36 | //! From these, you can see that the first argument is a format string. It is | |
37 | //! required by the compiler for this to be a string literal; it cannot be a | |
38 | //! variable passed in (in order to perform validity checking). The compiler | |
39 | //! will then parse the format string and determine if the list of arguments | |
40 | //! provided is suitable to pass to this format string. | |
41 | //! | |
c34b1796 | 42 | //! ## Positional parameters |
1a4d82fc JJ |
43 | //! |
44 | //! Each formatting argument is allowed to specify which value argument it's | |
45 | //! referencing, and if omitted it is assumed to be "the next argument". For | |
46 | //! example, the format string `{} {} {}` would take three parameters, and they | |
47 | //! would be formatted in the same order as they're given. The format string | |
48 | //! `{2} {1} {0}`, however, would format arguments in reverse order. | |
49 | //! | |
50 | //! Things can get a little tricky once you start intermingling the two types of | |
51 | //! positional specifiers. The "next argument" specifier can be thought of as an | |
52 | //! iterator over the argument. Each time a "next argument" specifier is seen, | |
53 | //! the iterator advances. This leads to behavior like this: | |
54 | //! | |
c34b1796 | 55 | //! ``` |
85aaf69f | 56 | //! format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2" |
1a4d82fc JJ |
57 | //! ``` |
58 | //! | |
59 | //! The internal iterator over the argument has not been advanced by the time | |
60 | //! the first `{}` is seen, so it prints the first argument. Then upon reaching | |
61 | //! the second `{}`, the iterator has advanced forward to the second argument. | |
62 | //! Essentially, parameters which explicitly name their argument do not affect | |
63 | //! parameters which do not name an argument in terms of positional specifiers. | |
64 | //! | |
65 | //! A format string is required to use all of its arguments, otherwise it is a | |
66 | //! compile-time error. You may refer to the same argument more than once in the | |
67 | //! format string, although it must always be referred to with the same type. | |
68 | //! | |
c34b1796 | 69 | //! ## Named parameters |
1a4d82fc JJ |
70 | //! |
71 | //! Rust itself does not have a Python-like equivalent of named parameters to a | |
72 | //! function, but the `format!` macro is a syntax extension which allows it to | |
73 | //! leverage named parameters. Named parameters are listed at the end of the | |
74 | //! argument list and have the syntax: | |
75 | //! | |
76 | //! ```text | |
77 | //! identifier '=' expression | |
78 | //! ``` | |
79 | //! | |
80 | //! For example, the following `format!` expressions all use named argument: | |
81 | //! | |
85aaf69f | 82 | //! ``` |
1a4d82fc | 83 | //! format!("{argument}", argument = "test"); // => "test" |
85aaf69f SL |
84 | //! format!("{name} {}", 1, name = 2); // => "2 1" |
85 | //! format!("{a} {c} {b}", a="a", b='b', c=3); // => "a 3 b" | |
1a4d82fc JJ |
86 | //! ``` |
87 | //! | |
c1a9b12d SL |
88 | //! It is not valid to put positional parameters (those without names) after |
89 | //! arguments which have names. Like with positional parameters, it is not | |
90 | //! valid to provide named parameters that are unused by the format string. | |
1a4d82fc | 91 | //! |
c34b1796 | 92 | //! ## Argument types |
1a4d82fc JJ |
93 | //! |
94 | //! Each argument's type is dictated by the format string. It is a requirement | |
95 | //! that every argument is only ever referred to by one type. For example, this | |
96 | //! is an invalid format string: | |
97 | //! | |
98 | //! ```text | |
99 | //! {0:x} {0:o} | |
100 | //! ``` | |
101 | //! | |
102 | //! This is invalid because the first argument is both referred to as a | |
103 | //! hexadecimal as well as an | |
104 | //! octal. | |
105 | //! | |
c1a9b12d SL |
106 | //! There are various parameters which do require a particular type, however. |
107 | //! Namely, the `{:.*}` syntax, which sets the number of numbers after the | |
108 | //! decimal in floating-point types: | |
c34b1796 AL |
109 | //! |
110 | //! ``` | |
111 | //! let formatted_number = format!("{:.*}", 2, 1.234567); | |
112 | //! | |
113 | //! assert_eq!("1.23", formatted_number) | |
114 | //! ``` | |
115 | //! | |
c1a9b12d SL |
116 | //! If this syntax is used, then the number of characters to print precedes the |
117 | //! actual object being formatted, and the number of characters must have the | |
118 | //! type `usize`. Although a `usize` can be printed with `{}`, it is invalid to | |
119 | //! reference an argument as such. For example this is another invalid format | |
120 | //! string: | |
1a4d82fc JJ |
121 | //! |
122 | //! ```text | |
123 | //! {:.*} {0} | |
124 | //! ``` | |
125 | //! | |
c34b1796 | 126 | //! ## Formatting traits |
1a4d82fc JJ |
127 | //! |
128 | //! When requesting that an argument be formatted with a particular type, you | |
129 | //! are actually requesting that an argument ascribes to a particular trait. | |
130 | //! This allows multiple actual types to be formatted via `{:x}` (like `i8` as | |
85aaf69f | 131 | //! well as `isize`). The current mapping of types to traits is: |
1a4d82fc | 132 | //! |
c1a9b12d SL |
133 | //! * *nothing* ⇒ [`Display`](trait.Display.html) |
134 | //! * `?` ⇒ [`Debug`](trait.Debug.html) | |
135 | //! * `o` ⇒ [`Octal`](trait.Octal.html) | |
136 | //! * `x` ⇒ [`LowerHex`](trait.LowerHex.html) | |
137 | //! * `X` ⇒ [`UpperHex`](trait.UpperHex.html) | |
138 | //! * `p` ⇒ [`Pointer`](trait.Pointer.html) | |
139 | //! * `b` ⇒ [`Binary`](trait.Binary.html) | |
140 | //! * `e` ⇒ [`LowerExp`](trait.LowerExp.html) | |
141 | //! * `E` ⇒ [`UpperExp`](trait.UpperExp.html) | |
1a4d82fc JJ |
142 | //! |
143 | //! What this means is that any type of argument which implements the | |
85aaf69f | 144 | //! `fmt::Binary` trait can then be formatted with `{:b}`. Implementations |
1a4d82fc JJ |
145 | //! are provided for these traits for a number of primitive types by the |
146 | //! standard library as well. If no format is specified (as in `{}` or `{:6}`), | |
85aaf69f | 147 | //! then the format trait used is the `Display` trait. |
1a4d82fc JJ |
148 | //! |
149 | //! When implementing a format trait for your own type, you will have to | |
150 | //! implement a method of the signature: | |
151 | //! | |
c34b1796 | 152 | //! ``` |
92a42be0 | 153 | //! # #![allow(dead_code)] |
1a4d82fc JJ |
154 | //! # use std::fmt; |
155 | //! # struct Foo; // our custom type | |
85aaf69f SL |
156 | //! # impl fmt::Display for Foo { |
157 | //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { | |
1a4d82fc JJ |
158 | //! # write!(f, "testing, testing") |
159 | //! # } } | |
160 | //! ``` | |
161 | //! | |
162 | //! Your type will be passed as `self` by-reference, and then the function | |
163 | //! should emit output into the `f.buf` stream. It is up to each format trait | |
164 | //! implementation to correctly adhere to the requested formatting parameters. | |
165 | //! The values of these parameters will be listed in the fields of the | |
166 | //! `Formatter` struct. In order to help with this, the `Formatter` struct also | |
167 | //! provides some helper methods. | |
168 | //! | |
169 | //! Additionally, the return value of this function is `fmt::Result` which is a | |
62682a34 SL |
170 | //! typedef to `Result<(), std::io::Error>` (also known as `std::io::Result<()>`). |
171 | //! Formatting implementations should ensure that they return errors from `write!` | |
1a4d82fc JJ |
172 | //! correctly (propagating errors upward). |
173 | //! | |
174 | //! An example of implementing the formatting traits would look | |
175 | //! like: | |
176 | //! | |
c34b1796 | 177 | //! ``` |
1a4d82fc | 178 | //! use std::fmt; |
1a4d82fc | 179 | //! |
85aaf69f | 180 | //! #[derive(Debug)] |
1a4d82fc | 181 | //! struct Vector2D { |
85aaf69f SL |
182 | //! x: isize, |
183 | //! y: isize, | |
1a4d82fc JJ |
184 | //! } |
185 | //! | |
85aaf69f | 186 | //! impl fmt::Display for Vector2D { |
1a4d82fc | 187 | //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
85aaf69f | 188 | //! // The `f` value implements the `Write` trait, which is what the |
1a4d82fc JJ |
189 | //! // write! macro is expecting. Note that this formatting ignores the |
190 | //! // various flags provided to format strings. | |
191 | //! write!(f, "({}, {})", self.x, self.y) | |
192 | //! } | |
193 | //! } | |
194 | //! | |
195 | //! // Different traits allow different forms of output of a type. The meaning | |
196 | //! // of this format is to print the magnitude of a vector. | |
197 | //! impl fmt::Binary for Vector2D { | |
198 | //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { | |
199 | //! let magnitude = (self.x * self.x + self.y * self.y) as f64; | |
200 | //! let magnitude = magnitude.sqrt(); | |
201 | //! | |
202 | //! // Respect the formatting flags by using the helper method | |
9346a6ac AL |
203 | //! // `pad_integral` on the Formatter object. See the method |
204 | //! // documentation for details, and the function `pad` can be used | |
205 | //! // to pad strings. | |
1a4d82fc | 206 | //! let decimals = f.precision().unwrap_or(3); |
9346a6ac | 207 | //! let string = format!("{:.*}", decimals, magnitude); |
c34b1796 | 208 | //! f.pad_integral(true, "", &string) |
1a4d82fc JJ |
209 | //! } |
210 | //! } | |
211 | //! | |
212 | //! fn main() { | |
213 | //! let myvector = Vector2D { x: 3, y: 4 }; | |
214 | //! | |
215 | //! println!("{}", myvector); // => "(3, 4)" | |
85aaf69f | 216 | //! println!("{:?}", myvector); // => "Vector2D {x: 3, y:4}" |
1a4d82fc JJ |
217 | //! println!("{:10.3b}", myvector); // => " 5.000" |
218 | //! } | |
219 | //! ``` | |
220 | //! | |
b039eaaf | 221 | //! ### `fmt::Display` vs `fmt::Debug` |
1a4d82fc JJ |
222 | //! |
223 | //! These two formatting traits have distinct purposes: | |
224 | //! | |
85aaf69f | 225 | //! - `fmt::Display` implementations assert that the type can be faithfully |
1a4d82fc | 226 | //! represented as a UTF-8 string at all times. It is **not** expected that |
85aaf69f SL |
227 | //! all types implement the `Display` trait. |
228 | //! - `fmt::Debug` implementations should be implemented for **all** public types. | |
1a4d82fc | 229 | //! Output will typically represent the internal state as faithfully as possible. |
85aaf69f SL |
230 | //! The purpose of the `Debug` trait is to facilitate debugging Rust code. In |
231 | //! most cases, using `#[derive(Debug)]` is sufficient and recommended. | |
1a4d82fc JJ |
232 | //! |
233 | //! Some examples of the output from both traits: | |
234 | //! | |
235 | //! ``` | |
c34b1796 | 236 | //! assert_eq!(format!("{} {:?}", 3, 4), "3 4"); |
1a4d82fc JJ |
237 | //! assert_eq!(format!("{} {:?}", 'a', 'b'), "a 'b'"); |
238 | //! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\""); | |
239 | //! ``` | |
240 | //! | |
c34b1796 | 241 | //! ## Related macros |
1a4d82fc JJ |
242 | //! |
243 | //! There are a number of related macros in the `format!` family. The ones that | |
244 | //! are currently implemented are: | |
245 | //! | |
246 | //! ```ignore | |
247 | //! format! // described above | |
9346a6ac | 248 | //! write! // first argument is a &mut io::Write, the destination |
1a4d82fc JJ |
249 | //! writeln! // same as write but appends a newline |
250 | //! print! // the format string is printed to the standard output | |
251 | //! println! // same as print but appends a newline | |
252 | //! format_args! // described below. | |
253 | //! ``` | |
254 | //! | |
c34b1796 | 255 | //! ### `write!` |
1a4d82fc JJ |
256 | //! |
257 | //! This and `writeln` are two macros which are used to emit the format string | |
258 | //! to a specified stream. This is used to prevent intermediate allocations of | |
259 | //! format strings and instead directly write the output. Under the hood, this | |
260 | //! function is actually invoking the `write` function defined in this module. | |
261 | //! Example usage is: | |
262 | //! | |
c34b1796 | 263 | //! ``` |
1a4d82fc | 264 | //! # #![allow(unused_must_use)] |
c34b1796 | 265 | //! use std::io::Write; |
1a4d82fc | 266 | //! let mut w = Vec::new(); |
85aaf69f | 267 | //! write!(&mut w, "Hello {}!", "world"); |
1a4d82fc JJ |
268 | //! ``` |
269 | //! | |
c34b1796 | 270 | //! ### `print!` |
1a4d82fc JJ |
271 | //! |
272 | //! This and `println` emit their output to stdout. Similarly to the `write!` | |
273 | //! macro, the goal of these macros is to avoid intermediate allocations when | |
274 | //! printing output. Example usage is: | |
275 | //! | |
c34b1796 | 276 | //! ``` |
1a4d82fc JJ |
277 | //! print!("Hello {}!", "world"); |
278 | //! println!("I have a newline {}", "character at the end"); | |
279 | //! ``` | |
280 | //! | |
c34b1796 AL |
281 | //! ### `format_args!` |
282 | //! | |
1a4d82fc JJ |
283 | //! This is a curious macro which is used to safely pass around |
284 | //! an opaque object describing the format string. This object | |
285 | //! does not require any heap allocations to create, and it only | |
286 | //! references information on the stack. Under the hood, all of | |
287 | //! the related macros are implemented in terms of this. First | |
288 | //! off, some example usage is: | |
289 | //! | |
290 | //! ``` | |
92a42be0 | 291 | //! # #![allow(unused_must_use)] |
1a4d82fc | 292 | //! use std::fmt; |
c34b1796 | 293 | //! use std::io::{self, Write}; |
1a4d82fc | 294 | //! |
1a4d82fc JJ |
295 | //! fmt::format(format_args!("this returns {}", "String")); |
296 | //! | |
c34b1796 | 297 | //! let mut some_writer = io::stdout(); |
85aaf69f | 298 | //! write!(&mut some_writer, "{}", format_args!("print with a {}", "macro")); |
1a4d82fc JJ |
299 | //! |
300 | //! fn my_fmt_fn(args: fmt::Arguments) { | |
c34b1796 | 301 | //! write!(&mut io::stdout(), "{}", args); |
1a4d82fc JJ |
302 | //! } |
303 | //! my_fmt_fn(format_args!("or a {} too", "function")); | |
1a4d82fc JJ |
304 | //! ``` |
305 | //! | |
306 | //! The result of the `format_args!` macro is a value of type `fmt::Arguments`. | |
307 | //! This structure can then be passed to the `write` and `format` functions | |
308 | //! inside this module in order to process the format string. | |
309 | //! The goal of this macro is to even further prevent intermediate allocations | |
310 | //! when dealing formatting strings. | |
311 | //! | |
312 | //! For example, a logging library could use the standard formatting syntax, but | |
313 | //! it would internally pass around this structure until it has been determined | |
314 | //! where output should go to. | |
315 | //! | |
c34b1796 | 316 | //! # Syntax |
1a4d82fc JJ |
317 | //! |
318 | //! The syntax for the formatting language used is drawn from other languages, | |
319 | //! so it should not be too alien. Arguments are formatted with python-like | |
320 | //! syntax, meaning that arguments are surrounded by `{}` instead of the C-like | |
321 | //! `%`. The actual grammar for the formatting syntax is: | |
322 | //! | |
323 | //! ```text | |
324 | //! format_string := <text> [ format <text> ] * | |
325 | //! format := '{' [ argument ] [ ':' format_spec ] '}' | |
326 | //! argument := integer | identifier | |
327 | //! | |
328 | //! format_spec := [[fill]align][sign]['#'][0][width]['.' precision][type] | |
329 | //! fill := character | |
330 | //! align := '<' | '^' | '>' | |
331 | //! sign := '+' | '-' | |
332 | //! width := count | |
333 | //! precision := count | '*' | |
334 | //! type := identifier | '' | |
335 | //! count := parameter | integer | |
336 | //! parameter := integer '$' | |
337 | //! ``` | |
338 | //! | |
c34b1796 | 339 | //! # Formatting Parameters |
1a4d82fc JJ |
340 | //! |
341 | //! Each argument being formatted can be transformed by a number of formatting | |
342 | //! parameters (corresponding to `format_spec` in the syntax above). These | |
343 | //! parameters affect the string representation of what's being formatted. This | |
344 | //! syntax draws heavily from Python's, so it may seem a bit familiar. | |
345 | //! | |
c34b1796 | 346 | //! ## Fill/Alignment |
1a4d82fc JJ |
347 | //! |
348 | //! The fill character is provided normally in conjunction with the `width` | |
349 | //! parameter. This indicates that if the value being formatted is smaller than | |
350 | //! `width` some extra characters will be printed around it. The extra | |
9cc50fc6 SL |
351 | //! characters are specified by `fill`, and the alignment can be one of the |
352 | //! following options: | |
1a4d82fc JJ |
353 | //! |
354 | //! * `<` - the argument is left-aligned in `width` columns | |
355 | //! * `^` - the argument is center-aligned in `width` columns | |
356 | //! * `>` - the argument is right-aligned in `width` columns | |
357 | //! | |
62682a34 SL |
358 | //! Note that alignment may not be implemented by some types. A good way |
359 | //! to ensure padding is applied is to format your input, then use this | |
360 | //! resulting string to pad your output. | |
361 | //! | |
b039eaaf | 362 | //! ## Sign/`#`/`0` |
1a4d82fc JJ |
363 | //! |
364 | //! These can all be interpreted as flags for a particular formatter. | |
365 | //! | |
b039eaaf | 366 | //! * `+` - This is intended for numeric types and indicates that the sign |
1a4d82fc JJ |
367 | //! should always be printed. Positive signs are never printed by |
368 | //! default, and the negative sign is only printed by default for the | |
b039eaaf | 369 | //! `Signed` trait. This flag indicates that the correct sign (`+` or `-`) |
1a4d82fc | 370 | //! should always be printed. |
b039eaaf SL |
371 | //! * `-` - Currently not used |
372 | //! * `#` - This flag is indicates that the "alternate" form of printing should | |
c1a9b12d SL |
373 | //! be used. The alternate forms are: |
374 | //! * `#?` - pretty-print the `Debug` formatting | |
b039eaaf SL |
375 | //! * `#x` - precedes the argument with a `0x` |
376 | //! * `#X` - precedes the argument with a `0x` | |
377 | //! * `#b` - precedes the argument with a `0b` | |
378 | //! * `#o` - precedes the argument with a `0o` | |
379 | //! * `0` - This is used to indicate for integer formats that the padding should | |
1a4d82fc | 380 | //! both be done with a `0` character as well as be sign-aware. A format |
c34b1796 | 381 | //! like `{:08}` would yield `00000001` for the integer `1`, while the |
1a4d82fc JJ |
382 | //! same format would yield `-0000001` for the integer `-1`. Notice that |
383 | //! the negative version has one fewer zero than the positive version. | |
384 | //! | |
c34b1796 | 385 | //! ## Width |
1a4d82fc JJ |
386 | //! |
387 | //! This is a parameter for the "minimum width" that the format should take up. | |
388 | //! If the value's string does not fill up this many characters, then the | |
389 | //! padding specified by fill/alignment will be used to take up the required | |
390 | //! space. | |
391 | //! | |
392 | //! The default fill/alignment for non-numerics is a space and left-aligned. The | |
393 | //! defaults for numeric formatters is also a space but with right-alignment. If | |
b039eaaf SL |
394 | //! the `0` flag is specified for numerics, then the implicit fill character is |
395 | //! `0`. | |
1a4d82fc | 396 | //! |
85aaf69f | 397 | //! The value for the width can also be provided as a `usize` in the list of |
1a4d82fc | 398 | //! parameters by using the `2$` syntax indicating that the second argument is a |
85aaf69f | 399 | //! `usize` specifying the width. |
1a4d82fc | 400 | //! |
c34b1796 | 401 | //! ## Precision |
1a4d82fc | 402 | //! |
9346a6ac AL |
403 | //! For non-numeric types, this can be considered a "maximum width". If the resulting string is |
404 | //! longer than this width, then it is truncated down to this many characters and only those are | |
405 | //! emitted. | |
1a4d82fc | 406 | //! |
d9579d0f | 407 | //! For integral types, this is ignored. |
1a4d82fc | 408 | //! |
9346a6ac AL |
409 | //! For floating-point types, this indicates how many digits after the decimal point should be |
410 | //! printed. | |
411 | //! | |
412 | //! There are three possible ways to specify the desired `precision`: | |
413 | //! | |
c1a9b12d SL |
414 | //! 1. An integer `.N`: |
415 | //! | |
416 | //! the integer `N` itself is the precision. | |
417 | //! | |
418 | //! 2. An integer followed by dollar sign `.N$`: | |
9346a6ac | 419 | //! |
c1a9b12d | 420 | //! use format *argument* `N` (which must be a `usize`) as the precision. |
9346a6ac | 421 | //! |
c1a9b12d | 422 | //! 3. An asterisk `.*`: |
9346a6ac | 423 | //! |
c1a9b12d SL |
424 | //! `.*` means that this `{...}` is associated with *two* format inputs rather than one: the |
425 | //! first input holds the `usize` precision, and the second holds the value to print. Note that | |
426 | //! in this case, if one uses the format string `{<arg>:<spec>.*}`, then the `<arg>` part refers | |
427 | //! to the *value* to print, and the `precision` must come in the input preceding `<arg>`. | |
9346a6ac AL |
428 | //! |
429 | //! For example, these: | |
430 | //! | |
431 | //! ``` | |
54a0048b | 432 | //! // Hello {arg 0 (x)} is {arg 1 (0.01) with precision specified inline (5)} |
9346a6ac AL |
433 | //! println!("Hello {0} is {1:.5}", "x", 0.01); |
434 | //! | |
54a0048b | 435 | //! // Hello {arg 1 (x)} is {arg 2 (0.01) with precision specified in arg 0 (5)} |
9346a6ac AL |
436 | //! println!("Hello {1} is {2:.0$}", 5, "x", 0.01); |
437 | //! | |
54a0048b | 438 | //! // Hello {arg 0 (x)} is {arg 2 (0.01) with precision specified in arg 1 (5)} |
9346a6ac AL |
439 | //! println!("Hello {0} is {2:.1$}", "x", 5, 0.01); |
440 | //! | |
54a0048b | 441 | //! // Hello {next arg (x)} is {second of next two args (0.01) with precision |
9346a6ac AL |
442 | //! // specified in first of next two args (5)} |
443 | //! println!("Hello {} is {:.*}", "x", 5, 0.01); | |
444 | //! | |
54a0048b | 445 | //! // Hello {next arg (x)} is {arg 2 (0.01) with precision |
9346a6ac AL |
446 | //! // specified in its predecessor (5)} |
447 | //! println!("Hello {} is {2:.*}", "x", 5, 0.01); | |
448 | //! ``` | |
449 | //! | |
450 | //! All print the same thing: | |
451 | //! | |
452 | //! ```text | |
453 | //! Hello x is 0.01000 | |
454 | //! ``` | |
455 | //! | |
456 | //! While these: | |
457 | //! | |
458 | //! ``` | |
459 | //! println!("{}, `{name:.*}` has 3 fractional digits", "Hello", 3, name=1234.56); | |
460 | //! println!("{}, `{name:.*}` has 3 characters", "Hello", 3, name="1234.56"); | |
461 | //! ``` | |
462 | //! | |
463 | //! print two significantly different things: | |
464 | //! | |
465 | //! ```text | |
466 | //! Hello, `1234.560` has 3 fractional digits | |
467 | //! Hello, `123` has 3 characters | |
468 | //! ``` | |
1a4d82fc | 469 | //! |
c34b1796 | 470 | //! # Escaping |
1a4d82fc JJ |
471 | //! |
472 | //! The literal characters `{` and `}` may be included in a string by preceding | |
473 | //! them with the same character. For example, the `{` character is escaped with | |
474 | //! `{{` and the `}` character is escaped with `}}`. | |
475 | ||
85aaf69f | 476 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 477 | |
92a42be0 SL |
478 | #[unstable(feature = "fmt_internals", issue = "0")] |
479 | pub use core::fmt::rt; | |
480 | #[stable(feature = "rust1", since = "1.0.0")] | |
481 | pub use core::fmt::{Formatter, Result, Write}; | |
482 | #[stable(feature = "rust1", since = "1.0.0")] | |
c34b1796 | 483 | pub use core::fmt::{Octal, Binary}; |
92a42be0 | 484 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 485 | pub use core::fmt::{Display, Debug}; |
92a42be0 | 486 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 487 | pub use core::fmt::{LowerHex, UpperHex, Pointer}; |
92a42be0 | 488 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 489 | pub use core::fmt::{LowerExp, UpperExp}; |
92a42be0 | 490 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 491 | pub use core::fmt::Error; |
92a42be0 | 492 | #[stable(feature = "rust1", since = "1.0.0")] |
9cc50fc6 | 493 | pub use core::fmt::{ArgumentV1, Arguments, write}; |
92a42be0 | 494 | #[stable(feature = "rust1", since = "1.0.0")] |
e9174d1e | 495 | pub use core::fmt::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple}; |
1a4d82fc | 496 | |
85aaf69f | 497 | use string; |
1a4d82fc JJ |
498 | |
499 | /// The format function takes a precompiled format string and a list of | |
500 | /// arguments, to return the resulting formatted string. | |
501 | /// | |
502 | /// # Arguments | |
503 | /// | |
504 | /// * args - a structure of arguments generated via the `format_args!` macro. | |
505 | /// | |
c34b1796 | 506 | /// # Examples |
1a4d82fc | 507 | /// |
c34b1796 | 508 | /// ``` |
1a4d82fc JJ |
509 | /// use std::fmt; |
510 | /// | |
511 | /// let s = fmt::format(format_args!("Hello, {}!", "world")); | |
512 | /// assert_eq!(s, "Hello, world!".to_string()); | |
513 | /// ``` | |
85aaf69f | 514 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
515 | pub fn format(args: Arguments) -> string::String { |
516 | let mut output = string::String::new(); | |
d9579d0f | 517 | let _ = output.write_fmt(args); |
1a4d82fc JJ |
518 | output |
519 | } |