Skip to content

Commit 2b4cdea

Browse files
committed
auto merge of rust-lang#14258 : alexcrichton/rust/dox-format-writer, r=cmr
This commit fills in the documentation holes for the FormatWriter trait which were previously accidentally left blank. Additionally, this adds the `write_fmt` method to the trait to allow usage of the `write!` macro with implementors of the `FormatWriter` trait. This is not useful for consumers of the standard library who should generally avoid the `FormatWriter` trait, but it is useful for consumers of the core library who are not using the standard library.
2 parents bf8648d + 14d3dbe commit 2b4cdea

File tree

2 files changed

+45
-4
lines changed

2 files changed

+45
-4
lines changed

src/libcore/fmt/mod.rs

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,16 +43,44 @@ pub mod rt;
4343

4444
pub type Result = result::Result<(), FormatError>;
4545

46-
/// dox
46+
/// The error type which is returned from formatting a message into a stream.
47+
///
48+
/// This type does not support transmission of an error other than that an error
49+
/// occurred. Any extra information must be arranged to be transmitted through
50+
/// some other means.
4751
pub enum FormatError {
48-
/// dox
52+
/// A generic write error occurred during formatting, no other information
53+
/// is transmitted via this variant.
4954
WriteError,
5055
}
5156

52-
/// dox
57+
/// A collection of methods that are required to format a message into a stream.
58+
///
59+
/// This trait is the type which this modules requires when formatting
60+
/// information. This is similar to the standard library's `io::Writer` trait,
61+
/// but it is only intended for use in libcore.
62+
///
63+
/// This trait should generally not be implemented by consumers of the standard
64+
/// library. The `write!` macro accepts an instance of `io::Writer`, and the
65+
/// `io::Writer` trait is favored over implementing this trait.
5366
pub trait FormatWriter {
54-
/// dox
67+
/// Writes a slice of bytes into this writer, returning whether the write
68+
/// succeeded.
69+
///
70+
/// This method can only succeed if the entire byte slice was successfully
71+
/// written, and this method will not return until all data has been
72+
/// written or an error occurs.
73+
///
74+
/// # Errors
75+
///
76+
/// This function will return an instance of `FormatError` on error.
5577
fn write(&mut self, bytes: &[u8]) -> Result;
78+
79+
/// Glue for usage of the `write!` macro with implementors of this trait.
80+
///
81+
/// This method should generally not be invoked manually, but rather through
82+
/// the `write!` macro itself.
83+
fn write_fmt(&mut self, args: &Arguments) -> Result { write(self, args) }
5684
}
5785

5886
/// A struct to represent both where to emit formatting strings to and how they

src/test/run-pass/colorful-write-macros.rs

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,22 @@
1414
#![feature(macro_rules)]
1515

1616
use std::io::MemWriter;
17+
use std::fmt;
18+
use std::fmt::FormatWriter;
1719

1820
struct Foo<'a> {
1921
writer: &'a mut Writer,
2022
other: &'a str,
2123
}
2224

25+
struct Bar;
26+
27+
impl fmt::FormatWriter for Bar {
28+
fn write(&mut self, _: &[u8]) -> fmt::Result {
29+
Ok(())
30+
}
31+
}
32+
2333
fn borrowing_writer_from_struct_and_formatting_struct_field(foo: Foo) {
2434
write!(foo.writer, "{}", foo.other);
2535
}
@@ -29,4 +39,7 @@ fn main() {
2939
write!(&mut w as &mut Writer, "");
3040
write!(&mut w, ""); // should coerce
3141
println!("ok");
42+
43+
let mut s = Bar;
44+
write!(&mut s, "test");
3245
}

0 commit comments

Comments
 (0)