mirror of https://github.com/rust-lang/rust.git
core: Document FormatWriter and allow `write!`
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.
This commit is contained in:
parent
2216eceea5
commit
14d3dbe292
|
@ -43,16 +43,44 @@ pub mod rt;
|
||||||
|
|
||||||
pub type Result = result::Result<(), FormatError>;
|
pub type Result = result::Result<(), FormatError>;
|
||||||
|
|
||||||
/// dox
|
/// The error type which is returned from formatting a message into a stream.
|
||||||
|
///
|
||||||
|
/// This type does not support transmission of an error other than that an error
|
||||||
|
/// occurred. Any extra information must be arranged to be transmitted through
|
||||||
|
/// some other means.
|
||||||
pub enum FormatError {
|
pub enum FormatError {
|
||||||
/// dox
|
/// A generic write error occurred during formatting, no other information
|
||||||
|
/// is transmitted via this variant.
|
||||||
WriteError,
|
WriteError,
|
||||||
}
|
}
|
||||||
|
|
||||||
/// dox
|
/// A collection of methods that are required to format a message into a stream.
|
||||||
|
///
|
||||||
|
/// This trait is the type which this modules requires when formatting
|
||||||
|
/// information. This is similar to the standard library's `io::Writer` trait,
|
||||||
|
/// but it is only intended for use in libcore.
|
||||||
|
///
|
||||||
|
/// This trait should generally not be implemented by consumers of the standard
|
||||||
|
/// library. The `write!` macro accepts an instance of `io::Writer`, and the
|
||||||
|
/// `io::Writer` trait is favored over implementing this trait.
|
||||||
pub trait FormatWriter {
|
pub trait FormatWriter {
|
||||||
/// dox
|
/// Writes a slice of bytes into this writer, returning whether the write
|
||||||
|
/// succeeded.
|
||||||
|
///
|
||||||
|
/// This method can only succeed if the entire byte slice was successfully
|
||||||
|
/// written, and this method will not return until all data has been
|
||||||
|
/// written or an error occurs.
|
||||||
|
///
|
||||||
|
/// # Errors
|
||||||
|
///
|
||||||
|
/// This function will return an instance of `FormatError` on error.
|
||||||
fn write(&mut self, bytes: &[u8]) -> Result;
|
fn write(&mut self, bytes: &[u8]) -> Result;
|
||||||
|
|
||||||
|
/// Glue for usage of the `write!` macro with implementors of this trait.
|
||||||
|
///
|
||||||
|
/// This method should generally not be invoked manually, but rather through
|
||||||
|
/// the `write!` macro itself.
|
||||||
|
fn write_fmt(&mut self, args: &Arguments) -> Result { write(self, args) }
|
||||||
}
|
}
|
||||||
|
|
||||||
/// A struct to represent both where to emit formatting strings to and how they
|
/// A struct to represent both where to emit formatting strings to and how they
|
||||||
|
|
|
@ -14,12 +14,22 @@
|
||||||
#![feature(macro_rules)]
|
#![feature(macro_rules)]
|
||||||
|
|
||||||
use std::io::MemWriter;
|
use std::io::MemWriter;
|
||||||
|
use std::fmt;
|
||||||
|
use std::fmt::FormatWriter;
|
||||||
|
|
||||||
struct Foo<'a> {
|
struct Foo<'a> {
|
||||||
writer: &'a mut Writer,
|
writer: &'a mut Writer,
|
||||||
other: &'a str,
|
other: &'a str,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
struct Bar;
|
||||||
|
|
||||||
|
impl fmt::FormatWriter for Bar {
|
||||||
|
fn write(&mut self, _: &[u8]) -> fmt::Result {
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
fn borrowing_writer_from_struct_and_formatting_struct_field(foo: Foo) {
|
fn borrowing_writer_from_struct_and_formatting_struct_field(foo: Foo) {
|
||||||
write!(foo.writer, "{}", foo.other);
|
write!(foo.writer, "{}", foo.other);
|
||||||
}
|
}
|
||||||
|
@ -29,4 +39,7 @@ fn main() {
|
||||||
write!(&mut w as &mut Writer, "");
|
write!(&mut w as &mut Writer, "");
|
||||||
write!(&mut w, ""); // should coerce
|
write!(&mut w, ""); // should coerce
|
||||||
println!("ok");
|
println!("ok");
|
||||||
|
|
||||||
|
let mut s = Bar;
|
||||||
|
write!(&mut s, "test");
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue