`format!` does not support width/alignment with `#x`

[dhardy]

I tried this code:

    println!("Next u64: {0:#X>18} = {0:>20}", rand::rng().next_u64());

The format! / format_args! docs are not exactly clear on how to combine width/alignment with formatting traits, but I expected the above to print out a right-aligned hex number (0x + 16 hex digits) followed by a right-aligned decimal representation of the same number.

It doesn't; instead I see an error:

6 |     println!("Next u64: {0:#X>18} = {0:>20}", rng.next_u64());
  |                              ^ expected `>` to occur after `:` in format string

If I omit the #, the code compiles, instead treating x as a filler. This is confusing since {0:x} is used to enable hexadecimal output, yet the number still gets printed in decimal form.

If I use 0x{0:X} or {0:#X} then the number is printed correctly, but without alignment.

(The format! docs are horrible to read as a reference by the way: far too much prose and no sign-posting of how edge cases are handled.)

rustc 1.90.0-nightly (ab68b0fb2 2025-07-08)

[ShE3py]

The right format is {0:>#18X}, the error message can probably be tweaked to “expected `>` to occur earlier”.
See the full syntax: https://doc.rust-lang.org/std/fmt/index.html#syntax

[dhardy]

Thanks. So not a bug, other than documentation (including error message).

I'm not sure whether to close this issue then (it's certainly not the first time I've found format! docs confusing). Good docs for macros are always hard.

[dhardy]

I notice that the Syntax section is right in the middle of the module docs and that those docs are very long. Moving the section to the beginning (or end) would increase visibility of this important section.

Alternatively, the "Usage" examples at the beginning could be expanded with one or more examples showing how to combine various formatting args. Maybe link to the "Syntax" section here, or move it to just after "Usage".

[ShE3py]

The syntax also seems incomplete? It doesn't mention binary/octal/etc. representations, only hexadecimal or identifier (?) and using any identifier don't print out that x? and X? are also available.

error: unknown format trait `zoro`
 --> src/main.rs:4:32
  |
4 |     println!("Next u64: {0:>#18zoro} = {0:>20}", rand::rng().next_u64());
  |                                ^^^^
  |
  = note: the only appropriate formatting traits are:
          - ``, which uses the `Display` trait
          - `?`, which uses the `Debug` trait
          - `e`, which uses the `LowerExp` trait
          - `E`, which uses the `UpperExp` trait
          - `o`, which uses the `Octal` trait
          - `p`, which uses the `Pointer` trait
          - `b`, which uses the `Binary` trait
          - `x`, which uses the `LowerHex` trait
          - `X`, which uses the `UpperHex` trait

error: could not compile `playground` (bin "playground") due to 1 previous error

@rustbot label +A-docs +A-diagnostics +A-fmt +E-easy -C-bug -needs-triage +C-discussion

[krikera]

@rustbot claim