Add examples to fmt precision

[steveklabnik]

Fixes #24656

r? @pnkfelix

I just added the examples, but if the wording needs expanded too, let me know what you think should be added :)

[Manishearth]

Perhaps have a comment above each one reading out what each one means? Something like "Hello {first argument (x)} is {second argument (0.01) with precision specified in zeroeth argument (5)}"

[Manishearth]

r=me with or without comments addressed, unless you specifically wanted Felix's r 😄

[pnkfelix]

@steveklabnik the additions seem fine (i.e. r=me); the suggestions noted by @Manishearth also seem like good changes.

Its funny (or perhaps sad); my original issue #24656 was that I could not find documentation for the actual meaning of .*.

• Yet such documentation can clearly be seen here: https://github.com/rust-lang/rust/blob/master/src/libcollections/fmt.rs#L106
• I have no explanation for how I overlooked that text in my repeated scans of the docs. Maybe I was looking at the code directly in a checkout that predated your addition from PR Document {:.*} #23493 ; anyway, sorry if my original issue text seemed shrill.
• Update: Maybe part of the reason for my confusion is that the text at https://github.com/rust-lang/rust/blob/master/src/libcollections/fmt.rs#L106 is presented as if it were an aside about requiring particular types for certain format parameters, but not about a breakdown of what each of the format parameters means. (and indeed, that makes sense, since line 106 is too early for an explanation of all the variants of the precision argument)

[pnkfelix]

Although, reading over that text from https://github.com/rust-lang/rust/blob/master/src/libcollections/fmt.rs#L106 now, it seems like there is a little room for improvement.

Namely: While that text does describe the meaning of {:.*}, it does not describe the meaning of {:.<num>}.

I.e. I might have guessed that {:.5} means that it should print five decimal places, but it actually means lookup the number of decimal places to print from the argument number five (right? That's what I at least infer from my reverse engineering in those examples I wrote.)

Update: I goofed, so I have crossed out some erroneous text from the above. Namely, the examples used {:.5$}, not {:.5}; the $ is what makes it interpret the 5 as "argument number five."

[pnkfelix]

So yes, on further reflection, while these changes are good, I think one more thing is needed: An expansion of the text at http://doc.rust-lang.org/nightly/std/fmt/index.html#precision that explains how the actual precision argument as written is interpreted.

And then you should probably consider moving my examples that you have transcribed into that section on the precision formatting parameter. Update: Ugh, I goofed again, you did put them into that section.

[Manishearth]

I think an explicit mention of the differences between * and $, and some more examples, would be helpful.

[pnkfelix]

So here is a draft of what we might write in the new precision section:

Precision

...
For floating-point types, this indicates how many digits after the decimal point should be printed.

There are three possible ways to specify the desired precision: (1.) an integer .N, (2.) an integer followed by dollar sign .N$, or (3.) an asterisk .*.

• The first specification, .N, means the integer N itself is the precision.
• The second, .N$, means use format argument N (which must be a usize) as the precision.
• Finally, .* means that this {...} is associated with two format inputs rather than one: the first input holds the usize precision, and the second holds the value to print. Note that in this case, if one uses the format string {<arg>:<spec>.*}, then the <arg> part refers to the value to print, and the precision must come in the input preceding <arg>.

For example, these:

// Hello {arg 0 (x)} is {arg 1 (0.01} with precision specified inline (5)}
println!("Hello {0} is {1:.5}", "x", 0.01);

// Hello {arg 1 (x)} is {arg 2 (0.01} with precision specified in arg 0 (5)}
println!("Hello {1} is {2:.0$}", 5, "x", 0.01);

// Hello {arg 0 (x)} is {arg 2 (0.01} with precision specified in arg 1 (5)}
println!("Hello {0} is {2:.1$}", "x", 5, 0.01);

// Hello {next arg (x)} is {second of next two args (0.01} with precision
//                          specified in first of next two args (5)}
println!("Hello {} is {:.*}",    "x", 5, 0.01);

// Hello {next arg (x)} is {arg 2 (0.01} with precision
//                          specified in its predecessor (5)}
println!("Hello {} is {2:.*}",   "x", 5, 0.01);

All print the same thing:

Hello x is 0.01000

While these:

println!("{}, `{name:.*}` has 3 fractional digits", "Hello", 3, name=1234.56);
println!("{}, `{name:.*}` has 3 characters", "Hello", 3, name="1234.56");

print two significantly different things:

Hello, `1234.560` has 3 fractional digits
Hello, `123` has 3 characters

Update: added a fifth example to the first series of Hello's to illustrate the .N format.

[pnkfelix]

(ah good doc is so hard...)

[Manishearth]

👍

[steveklabnik]

(ah good doc is so hard...)

Right? Thanks so much :)

[steveklabnik]

@bors: r+ rollup

[bors]

📌 Commit eb5b842 has been approved by steveklabnik

[steveklabnik]

(Since @pnkfelix ended up writing the doc, i'll r+ it)

[steveklabnik]

Sneaking this into #24786 as well

[steveklabnik]

@bors: r+ rollup

[bors]

📌 Commit 064972c has been approved by steveklabnik