Documentation: write_fmt is unclear

[kornelski]

I'm trying to upgrade code that worked in 0.10/0.11-pre (implementation of fmt::Show):

write!(formatter.buf, "\\#{:02x}{:02x}{:02x}", self.r, self.g, self.b),

I've found a write_fmt method that sounds like what I need, but it's undocumented:

http://doc.rust-lang.org/core/fmt/struct.Formatter.html#method.write_fmt

Linked Arguments documentation suggests usnig format_args!():

http://doc.rust-lang.org/core/fmt/struct.Arguments.html

but the usage I'd expect:

formatter.write_fmt(format_args!("\\#{:02x}{:02x}{:02x}", self.r, self.g, self.b)),

fails with "format argument must be a string literal.", which left me lost. If really supports only literals as arguments then it's totally useless, but if I'm doing something wrong, then the docs/compiler don't help me figure this out.

[bluss]

The docs are not up to date. I think this should work for you:

write!(formatter, "#{:02x}{:02x}{:02x}", self.r, self.g, self.b)

# doesn't need to be escaped anymore, and you can use write! directly on the formatter. It should have been documented at http://doc.rust-lang.org/std/fmt/index.html but it has not quite been updated.

*Updated to not ignore the return value. write! has a return value -- you can return it from the fmt method.

[kornelski]

That works, thanks!

Shall I leave the issue open as a reminder to update the docs?

[sfackler]

Errors from the formatter should be propagated upstream instead of being ignored.

try!(write!(formatter, "#{:02x}{:02x}{:02x}", self.r, self.g, self.b))

[steveklabnik]

@pornel yes, please leave it open, i will tag it 'docs'

[steveklabnik]

I just opened a PR to remove that faulty paragraph.

[huonw]

The docs are up-to-date, it's just format_args passes the created structure into a closure/function passed as the first argument. See here for more details.