Rust Reference ยท Macros
Rust format specifiers: width, precision, fill and more
Complete reference for Rust format specifiers used by println! and format!: fill, alignment, sign, #, 0, width, precision, and the x, b, o, e, p and ? traits.
Everything after the colon in a placeholder such as {:>8.2} is a format specifier. It controls how the value is turned into text: the minimum width, the padding character, alignment, the number of decimals, the number base and which formatting trait is used. The specifiers work the same in println!, format!, write!, panic! and every other macro built on format_args!.
The grammar of a placeholder is {argument:fill align sign # 0 width .precision type}, where every part is optional.
println!("{:*^11}", "hi"); // ****hi***** println!("{:08.3}", 3.14159); // 0003.142 println!("{:#x}", 255); // 0xff
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
{ [argument] [ ":" [[fill] align] [sign] ["#"] ["0"] [width] ["." precision] [type] ] }
| Part | Description |
|---|---|
argument |
Index (0), name (name) or nothing (next positional). |
fill |
Any single character used for padding; default is a space. Must be followed by an alignment. |
align |
< left, ^ center, > right. Default: left for text, right for numbers. |
sign |
+ always shows the sign, including for positive numbers. (- is accepted but has no effect.) |
# |
Alternate form: 0x, 0o, 0b prefixes for bases; pretty-printing for ?. |
0 |
Pad numbers with zeros after the sign and prefix; the width must be given. |
width |
Minimum number of characters: a number, name$ or index$. |
.precision |
Digits after the point for floats; maximum characters for strings; .* takes it from the next argument; .name$ is also allowed. |
type |
Empty = Display; ? Debug; x X hex; o octal; b binary; e E scientific; p pointer. |
Returns: these are part of the format string, not a function, so there is no return value.
Errors / panics / edge cases: unknown specifiers, a 0 flag without a sensible type, or a missing width argument are compile errors. A type that does not implement the chosen trait (for example {:x} on a f64) is a compile error as well.
Usage notes
- Precision on integers is not allowed to mean decimals;
{:.2}on an integer is accepted by the macro but has no effect. - Width is a minimum; text longer than the width is never cut. Only precision truncates strings. Width counts
chars, not display columns, so wide characters and combining marks can misalign tables. 0flag:{:05}gives00042and{:+06}gives+00042. Negative numbers become-0042. The flag overrides fill and alignment.- Hex of negative integers prints the two's complement bit pattern of the type (
-1i8isff).{:#06x}counts the0xprefix in the width. - Floats:
{}prints the shortest text that round-trips;{:.1}rounds the exact binary value, so a number like0.25, which is exactly representable, rounds to even (0.2).{:?}on1.0prints1.0, while{}prints1. - Debug of strings adds quotes and escapes;
{:#?}pretty-prints nested structs across lines. - Width applies via
Formatter::pad. Your ownDisplayignores width unless it forwards tof.pad(...)orf.pad_integral(...), or usesf.width()itself. {:p}prints an address and is not deterministic between runs.- Escaping:
{{and}}print literal braces; a%has no special meaning.