1 // Copyright 2013-2015 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
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.
11 //! Utilities for formatting and printing `String`s
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.
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.
22 //! Some examples of the `format!` extension are:
25 //! format!("Hello"); // => "Hello"
26 //! format!("Hello, {}!", "world"); // => "Hello, world!"
27 //! format!("The number is {}", 1); // => "The number is 1"
28 //! format!("{:?}", (3, 4)); // => "(3, 4)"
29 //! format!("{value}", value=4); // => "4"
30 //! format!("{} {}", 1, 2); // => "1 2"
31 //! format!("{:04}", 42); // => "0042" with leading zeros
34 //! From these, you can see that the first argument is a format string. It is
35 //! required by the compiler for this to be a string literal; it cannot be a
36 //! variable passed in (in order to perform validity checking). The compiler
37 //! will then parse the format string and determine if the list of arguments
38 //! provided is suitable to pass to this format string.
40 //! ## Positional parameters
42 //! Each formatting argument is allowed to specify which value argument it's
43 //! referencing, and if omitted it is assumed to be "the next argument". For
44 //! example, the format string `{} {} {}` would take three parameters, and they
45 //! would be formatted in the same order as they're given. The format string
46 //! `{2} {1} {0}`, however, would format arguments in reverse order.
48 //! Things can get a little tricky once you start intermingling the two types of
49 //! positional specifiers. The "next argument" specifier can be thought of as an
50 //! iterator over the argument. Each time a "next argument" specifier is seen,
51 //! the iterator advances. This leads to behavior like this:
54 //! format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2"
57 //! The internal iterator over the argument has not been advanced by the time
58 //! the first `{}` is seen, so it prints the first argument. Then upon reaching
59 //! the second `{}`, the iterator has advanced forward to the second argument.
60 //! Essentially, parameters which explicitly name their argument do not affect
61 //! parameters which do not name an argument in terms of positional specifiers.
63 //! A format string is required to use all of its arguments, otherwise it is a
64 //! compile-time error. You may refer to the same argument more than once in the
65 //! format string, although it must always be referred to with the same type.
67 //! ## Named parameters
69 //! Rust itself does not have a Python-like equivalent of named parameters to a
70 //! function, but the `format!` macro is a syntax extension which allows it to
71 //! leverage named parameters. Named parameters are listed at the end of the
72 //! argument list and have the syntax:
75 //! identifier '=' expression
78 //! For example, the following `format!` expressions all use named argument:
81 //! format!("{argument}", argument = "test"); // => "test"
82 //! format!("{name} {}", 1, name = 2); // => "2 1"
83 //! format!("{a} {c} {b}", a="a", b='b', c=3); // => "a 3 b"
86 //! It is not valid to put positional parameters (those without names) after
87 //! arguments which have names. Like with positional parameters, it is not
88 //! valid to provide named parameters that are unused by the format string.
92 //! Each argument's type is dictated by the format string. It is a requirement
93 //! that every argument is only ever referred to by one type. For example, this
94 //! is an invalid format string:
100 //! This is invalid because the first argument is both referred to as a
101 //! hexadecimal as well as an
104 //! There are various parameters which do require a particular type, however.
105 //! An example is the `{:.*}` syntax, which sets the number of decimal places
106 //! in floating-point types:
109 //! let formatted_number = format!("{:.*}", 2, 1.234567);
111 //! assert_eq!("1.23", formatted_number)
114 //! If this syntax is used, then the number of characters to print precedes the
115 //! actual object being formatted, and the number of characters must have the
116 //! type `usize`. Although a `usize` can be printed with `{}`, it is invalid to
117 //! reference an argument as such. For example this is another invalid format
124 //! ## Formatting traits
126 //! When requesting that an argument be formatted with a particular type, you
127 //! are actually requesting that an argument ascribes to a particular trait.
128 //! This allows multiple actual types to be formatted via `{:x}` (like `i8` as
129 //! well as `isize`). The current mapping of types to traits is:
131 //! * *nothing* ⇒ [`Display`](trait.Display.html)
132 //! * `?` ⇒ [`Debug`](trait.Debug.html)
133 //! * `o` ⇒ [`Octal`](trait.Octal.html)
134 //! * `x` ⇒ [`LowerHex`](trait.LowerHex.html)
135 //! * `X` ⇒ [`UpperHex`](trait.UpperHex.html)
136 //! * `p` ⇒ [`Pointer`](trait.Pointer.html)
137 //! * `b` ⇒ [`Binary`](trait.Binary.html)
138 //! * `e` ⇒ [`LowerExp`](trait.LowerExp.html)
139 //! * `E` ⇒ [`UpperExp`](trait.UpperExp.html)
141 //! What this means is that any type of argument which implements the
142 //! `fmt::Binary` trait can then be formatted with `{:b}`. Implementations
143 //! are provided for these traits for a number of primitive types by the
144 //! standard library as well. If no format is specified (as in `{}` or `{:6}`),
145 //! then the format trait used is the `Display` trait.
147 //! When implementing a format trait for your own type, you will have to
148 //! implement a method of the signature:
151 //! # #![allow(dead_code)]
153 //! # struct Foo; // our custom type
154 //! # impl fmt::Display for Foo {
155 //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
156 //! # write!(f, "testing, testing")
160 //! Your type will be passed as `self` by-reference, and then the function
161 //! should emit output into the `f.buf` stream. It is up to each format trait
162 //! implementation to correctly adhere to the requested formatting parameters.
163 //! The values of these parameters will be listed in the fields of the
164 //! `Formatter` struct. In order to help with this, the `Formatter` struct also
165 //! provides some helper methods.
167 //! Additionally, the return value of this function is `fmt::Result` which is a
168 //! typedef to `Result<(), std::io::Error>` (also known as `std::io::Result<()>`).
169 //! Formatting implementations should ensure that they return errors from `write!`
170 //! correctly (propagating errors upward).
172 //! An example of implementing the formatting traits would look
179 //! struct Vector2D {
184 //! impl fmt::Display for Vector2D {
185 //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
186 //! // The `f` value implements the `Write` trait, which is what the
187 //! // write! macro is expecting. Note that this formatting ignores the
188 //! // various flags provided to format strings.
189 //! write!(f, "({}, {})", self.x, self.y)
193 //! // Different traits allow different forms of output of a type. The meaning
194 //! // of this format is to print the magnitude of a vector.
195 //! impl fmt::Binary for Vector2D {
196 //! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
197 //! let magnitude = (self.x * self.x + self.y * self.y) as f64;
198 //! let magnitude = magnitude.sqrt();
200 //! // Respect the formatting flags by using the helper method
201 //! // `pad_integral` on the Formatter object. See the method
202 //! // documentation for details, and the function `pad` can be used
203 //! // to pad strings.
204 //! let decimals = f.precision().unwrap_or(3);
205 //! let string = format!("{:.*}", decimals, magnitude);
206 //! f.pad_integral(true, "", &string)
211 //! let myvector = Vector2D { x: 3, y: 4 };
213 //! println!("{}", myvector); // => "(3, 4)"
214 //! println!("{:?}", myvector); // => "Vector2D {x: 3, y:4}"
215 //! println!("{:10.3b}", myvector); // => " 5.000"
219 //! ### `fmt::Display` vs `fmt::Debug`
221 //! These two formatting traits have distinct purposes:
223 //! - `fmt::Display` implementations assert that the type can be faithfully
224 //! represented as a UTF-8 string at all times. It is **not** expected that
225 //! all types implement the `Display` trait.
226 //! - `fmt::Debug` implementations should be implemented for **all** public types.
227 //! Output will typically represent the internal state as faithfully as possible.
228 //! The purpose of the `Debug` trait is to facilitate debugging Rust code. In
229 //! most cases, using `#[derive(Debug)]` is sufficient and recommended.
231 //! Some examples of the output from both traits:
234 //! assert_eq!(format!("{} {:?}", 3, 4), "3 4");
235 //! assert_eq!(format!("{} {:?}", 'a', 'b'), "a 'b'");
236 //! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\"");
239 //! ## Related macros
241 //! There are a number of related macros in the `format!` family. The ones that
242 //! are currently implemented are:
245 //! format! // described above
246 //! write! // first argument is a &mut io::Write, the destination
247 //! writeln! // same as write but appends a newline
248 //! print! // the format string is printed to the standard output
249 //! println! // same as print but appends a newline
250 //! format_args! // described below.
255 //! This and `writeln` are two macros which are used to emit the format string
256 //! to a specified stream. This is used to prevent intermediate allocations of
257 //! format strings and instead directly write the output. Under the hood, this
258 //! function is actually invoking the `write` function defined in this module.
259 //! Example usage is:
262 //! # #![allow(unused_must_use)]
263 //! use std::io::Write;
264 //! let mut w = Vec::new();
265 //! write!(&mut w, "Hello {}!", "world");
270 //! This and `println` emit their output to stdout. Similarly to the `write!`
271 //! macro, the goal of these macros is to avoid intermediate allocations when
272 //! printing output. Example usage is:
275 //! print!("Hello {}!", "world");
276 //! println!("I have a newline {}", "character at the end");
279 //! ### `format_args!`
281 //! This is a curious macro which is used to safely pass around
282 //! an opaque object describing the format string. This object
283 //! does not require any heap allocations to create, and it only
284 //! references information on the stack. Under the hood, all of
285 //! the related macros are implemented in terms of this. First
286 //! off, some example usage is:
289 //! # #![allow(unused_must_use)]
291 //! use std::io::{self, Write};
293 //! let mut some_writer = io::stdout();
294 //! write!(&mut some_writer, "{}", format_args!("print with a {}", "macro"));
296 //! fn my_fmt_fn(args: fmt::Arguments) {
297 //! write!(&mut io::stdout(), "{}", args);
299 //! my_fmt_fn(format_args!(", or a {} too", "function"));
302 //! The result of the `format_args!` macro is a value of type `fmt::Arguments`.
303 //! This structure can then be passed to the `write` and `format` functions
304 //! inside this module in order to process the format string.
305 //! The goal of this macro is to even further prevent intermediate allocations
306 //! when dealing formatting strings.
308 //! For example, a logging library could use the standard formatting syntax, but
309 //! it would internally pass around this structure until it has been determined
310 //! where output should go to.
314 //! The syntax for the formatting language used is drawn from other languages,
315 //! so it should not be too alien. Arguments are formatted with Python-like
316 //! syntax, meaning that arguments are surrounded by `{}` instead of the C-like
317 //! `%`. The actual grammar for the formatting syntax is:
320 //! format_string := <text> [ format <text> ] *
321 //! format := '{' [ argument ] [ ':' format_spec ] '}'
322 //! argument := integer | identifier
324 //! format_spec := [[fill]align][sign]['#'][0][width]['.' precision][type]
325 //! fill := character
326 //! align := '<' | '^' | '>'
327 //! sign := '+' | '-'
329 //! precision := count | '*'
330 //! type := identifier | ''
331 //! count := parameter | integer
332 //! parameter := argument '$'
335 //! # Formatting Parameters
337 //! Each argument being formatted can be transformed by a number of formatting
338 //! parameters (corresponding to `format_spec` in the syntax above). These
339 //! parameters affect the string representation of what's being formatted. This
340 //! syntax draws heavily from Python's, so it may seem a bit familiar.
342 //! ## Fill/Alignment
344 //! The fill character is provided normally in conjunction with the `width`
345 //! parameter. This indicates that if the value being formatted is smaller than
346 //! `width` some extra characters will be printed around it. The extra
347 //! characters are specified by `fill`, and the alignment can be one of the
348 //! following options:
350 //! * `<` - the argument is left-aligned in `width` columns
351 //! * `^` - the argument is center-aligned in `width` columns
352 //! * `>` - the argument is right-aligned in `width` columns
354 //! Note that alignment may not be implemented by some types. A good way
355 //! to ensure padding is applied is to format your input, then use this
356 //! resulting string to pad your output.
360 //! These can all be interpreted as flags for a particular formatter.
362 //! * `+` - This is intended for numeric types and indicates that the sign
363 //! should always be printed. Positive signs are never printed by
364 //! default, and the negative sign is only printed by default for the
365 //! `Signed` trait. This flag indicates that the correct sign (`+` or `-`)
366 //! should always be printed.
367 //! * `-` - Currently not used
368 //! * `#` - This flag is indicates that the "alternate" form of printing should
369 //! be used. The alternate forms are:
370 //! * `#?` - pretty-print the `Debug` formatting
371 //! * `#x` - precedes the argument with a `0x`
372 //! * `#X` - precedes the argument with a `0x`
373 //! * `#b` - precedes the argument with a `0b`
374 //! * `#o` - precedes the argument with a `0o`
375 //! * `0` - This is used to indicate for integer formats that the padding should
376 //! both be done with a `0` character as well as be sign-aware. A format
377 //! like `{:08}` would yield `00000001` for the integer `1`, while the
378 //! same format would yield `-0000001` for the integer `-1`. Notice that
379 //! the negative version has one fewer zero than the positive version.
383 //! This is a parameter for the "minimum width" that the format should take up.
384 //! If the value's string does not fill up this many characters, then the
385 //! padding specified by fill/alignment will be used to take up the required
388 //! The default fill/alignment for non-numerics is a space and left-aligned. The
389 //! defaults for numeric formatters is also a space but with right-alignment. If
390 //! the `0` flag is specified for numerics, then the implicit fill character is
393 //! The value for the width can also be provided as a `usize` in the list of
394 //! parameters by using the dollar syntax indicating that the second argument is
395 //! a `usize` specifying the width, for example:
398 //! // All of these print "Hello x !"
399 //! println!("Hello {:5}!", "x");
400 //! println!("Hello {:1$}!", "x", 5);
401 //! println!("Hello {1:0$}!", 5, "x");
402 //! println!("Hello {:width$}!", "x", width = 5);
405 //! Referring to an argument with the dollar syntax does not affect the "next
406 //! argument" counter, so it's usually a good idea to refer to arguments by
407 //! position, or use named arguments.
411 //! For non-numeric types, this can be considered a "maximum width". If the resulting string is
412 //! longer than this width, then it is truncated down to this many characters and that truncated
413 //! value is emitted with proper `fill`, `alignment` and `width` if those parameters are set.
415 //! For integral types, this is ignored.
417 //! For floating-point types, this indicates how many digits after the decimal point should be
420 //! There are three possible ways to specify the desired `precision`:
422 //! 1. An integer `.N`:
424 //! the integer `N` itself is the precision.
426 //! 2. An integer or name followed by dollar sign `.N$`:
428 //! use format *argument* `N` (which must be a `usize`) as the precision.
430 //! 3. An asterisk `.*`:
432 //! `.*` means that this `{...}` is associated with *two* format inputs rather than one: the
433 //! first input holds the `usize` precision, and the second holds the value to print. Note that
434 //! in this case, if one uses the format string `{<arg>:<spec>.*}`, then the `<arg>` part refers
435 //! to the *value* to print, and the `precision` must come in the input preceding `<arg>`.
437 //! For example, the following calls all print the same thing `Hello x is 0.01000`:
440 //! // Hello {arg 0 ("x")} is {arg 1 (0.01) with precision specified inline (5)}
441 //! println!("Hello {0} is {1:.5}", "x", 0.01);
443 //! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision specified in arg 0 (5)}
444 //! println!("Hello {1} is {2:.0$}", 5, "x", 0.01);
446 //! // Hello {arg 0 ("x")} is {arg 2 (0.01) with precision specified in arg 1 (5)}
447 //! println!("Hello {0} is {2:.1$}", "x", 5, 0.01);
449 //! // Hello {next arg ("x")} is {second of next two args (0.01) with precision
450 //! // specified in first of next two args (5)}
451 //! println!("Hello {} is {:.*}", "x", 5, 0.01);
453 //! // Hello {next arg ("x")} is {arg 2 (0.01) with precision
454 //! // specified in its predecessor (5)}
455 //! println!("Hello {} is {2:.*}", "x", 5, 0.01);
457 //! // Hello {next arg ("x")} is {arg "number" (0.01) with precision specified
458 //! // in arg "prec" (5)}
459 //! println!("Hello {} is {number:.prec$}", "x", prec = 5, number = 0.01);
465 //! println!("{}, `{name:.*}` has 3 fractional digits", "Hello", 3, name=1234.56);
466 //! println!("{}, `{name:.*}` has 3 characters", "Hello", 3, name="1234.56");
467 //! println!("{}, `{name:>8.*}` has 3 right-aligned characters", "Hello", 3, name="1234.56");
470 //! print two significantly different things:
473 //! Hello, `1234.560` has 3 fractional digits
474 //! Hello, `123` has 3 characters
475 //! Hello, ` 123` has 3 right-aligned characters
480 //! The literal characters `{` and `}` may be included in a string by preceding
481 //! them with the same character. For example, the `{` character is escaped with
482 //! `{{` and the `}` character is escaped with `}}`.
484 #![stable(feature = "rust1", since = "1.0.0")]
486 #[unstable(feature = "fmt_internals", issue = "0")]
487 pub use core::fmt::rt;
488 #[stable(feature = "rust1", since = "1.0.0")]
489 pub use core::fmt::{Formatter, Result, Write};
490 #[stable(feature = "rust1", since = "1.0.0")]
491 pub use core::fmt::{Octal, Binary};
492 #[stable(feature = "rust1", since = "1.0.0")]
493 pub use core::fmt::{Display, Debug};
494 #[stable(feature = "rust1", since = "1.0.0")]
495 pub use core::fmt::{LowerHex, UpperHex, Pointer};
496 #[stable(feature = "rust1", since = "1.0.0")]
497 pub use core::fmt::{LowerExp, UpperExp};
498 #[stable(feature = "rust1", since = "1.0.0")]
499 pub use core::fmt::Error;
500 #[stable(feature = "rust1", since = "1.0.0")]
501 pub use core::fmt::{ArgumentV1, Arguments, write};
502 #[stable(feature = "rust1", since = "1.0.0")]
503 pub use core::fmt::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple};
507 /// The format function takes a precompiled format string and a list of
508 /// arguments, to return the resulting formatted string.
512 /// * args - a structure of arguments generated via the `format_args!` macro.
521 /// let s = fmt::format(format_args!("Hello, {}!", "world"));
522 /// assert_eq!(s, "Hello, world!");
525 /// Please note that using [`format!`][format!] might be preferrable.
529 /// let s = format!("Hello, {}!", "world");
530 /// assert_eq!(s, "Hello, world!");
533 /// [format!]: ../macro.format!.html
534 #[stable(feature = "rust1", since = "1.0.0")]
535 pub fn format(args: Arguments) -> string::String {
536 let mut output = string::String::new();
537 let _ = output.write_fmt(args);