Trait std::io::Write
[−]
[src]
pub trait Write { fn write(&mut self, buf: &[u8]) -> Result<usize>; fn flush(&mut self) -> Result<()>; fn write_all(&mut self, buf: &[u8]) -> Result<()> { ... } fn write_fmt(&mut self, fmt: Arguments) -> Result<()> { ... } fn by_ref(&mut self) -> &mut Self where Self: Sized { ... } fn broadcast<W: Write>(self, other: W) -> Broadcast<Self, W> where Self: Sized { ... } }
A trait for objects which are byte-oriented sinks.
Implementors of the Write
`Write` trait are sometimes called 'writers'.
Writers are defined by two required methods, write()
`write()and
` and flush()
`flush()`:
The
write()
`write()` method will attempt to write some data into the object, returning how many bytes were successfully written.The
flush()
`flush()` method is useful for adaptors and explicit buffers themselves for ensuring that all buffered data has been pushed out to the 'true sink'.
Writers are intended to be composable with one another. Many implementors
throughout std::io
`std::iotake and provide types which implement the
Write`
trait.
Examples
fn main() { use std::io::prelude::*; use std::fs::File; fn foo() -> std::io::Result<()> { let mut buffer = try!(File::create("foo.txt")); try!(buffer.write(b"some bytes")); Ok(()) } }use std::io::prelude::*; use std::fs::File; let mut buffer = try!(File::create("foo.txt")); try!(buffer.write(b"some bytes"));
Required Methods
fn write(&mut self, buf: &[u8]) -> Result<usize>
Write a buffer into this object, returning how many bytes were written.
This function will attempt to write the entire contents of buf
`buf, but the entire write may not succeed, or the write may also generate an error. A call to
write` represents at most one attempt to write to
any wrapped object.
Calls to write
`writeare not guaranteed to block waiting for data to be written, and a write which would otherwise block can be indicated through an
Err` variant.
If the return value is Ok(n)
`Ok(n)then it must be guaranteed that
0 <= n <= buf.len(). A return value of
0` typically means that the
underlying object is no longer able to accept bytes and will likely not
be able to in the future as well, or that the buffer provided is empty.
Errors
Each call to write
`write` may generate an I/O error indicating that the
operation could not be completed. If an error is returned then no bytes
in the buffer were written to this writer.
It is not considered an error if the entire buffer could not be written to this writer.
Examples
fn main() { use std::io::prelude::*; use std::fs::File; fn foo() -> std::io::Result<()> { let mut buffer = try!(File::create("foo.txt")); try!(buffer.write(b"some bytes")); Ok(()) } }use std::io::prelude::*; use std::fs::File; let mut buffer = try!(File::create("foo.txt")); try!(buffer.write(b"some bytes"));
fn flush(&mut self) -> Result<()>
Flush this output stream, ensuring that all intermediately buffered contents reach their destination.
Errors
It is considered an error if not all bytes could be written due to I/O errors or EOF being reached.
Examples
fn main() { use std::io::prelude::*; use std::io::BufWriter; use std::fs::File; fn foo() -> std::io::Result<()> { let mut buffer = BufWriter::new(try!(File::create("foo.txt"))); try!(buffer.write(b"some bytes")); try!(buffer.flush()); Ok(()) } }use std::io::prelude::*; use std::io::BufWriter; use std::fs::File; let mut buffer = BufWriter::new(try!(File::create("foo.txt"))); try!(buffer.write(b"some bytes")); try!(buffer.flush());
Provided Methods
fn write_all(&mut self, buf: &[u8]) -> Result<()>
Attempts to write an entire buffer into this write.
This method will continuously call write
`write` while there is more data to
write. This method will not return until the entire buffer has been
successfully written or an error occurs. The first error generated from
this method will be returned.
Errors
This function will return the first error that write
`write` returns.
Examples
fn main() { use std::io::prelude::*; use std::fs::File; fn foo() -> std::io::Result<()> { let mut buffer = try!(File::create("foo.txt")); try!(buffer.write_all(b"some bytes")); Ok(()) } }use std::io::prelude::*; use std::fs::File; let mut buffer = try!(File::create("foo.txt")); try!(buffer.write_all(b"some bytes"));
fn write_fmt(&mut self, fmt: Arguments) -> Result<()>
Writes a formatted string into this writer, returning any error encountered.
This method is primarily used to interface with the
format_args!
macro, but it is rare that this should
explicitly be called. The write!
`write!` macro should be favored to
invoke this method instead.
This function internally uses the write_all
method on
this trait and hence will continuously write data so long as no errors
are received. This also means that partial writes are not indicated in
this signature.
Errors
This function will return any I/O error reported while formatting.
Examples
fn main() { use std::io::prelude::*; use std::fs::File; fn foo() -> std::io::Result<()> { let mut buffer = try!(File::create("foo.txt")); // this call try!(write!(buffer, "{:.*}", 2, 1.234567)); // turns into this: try!(buffer.write_fmt(format_args!("{:.*}", 2, 1.234567))); Ok(()) } }use std::io::prelude::*; use std::fs::File; let mut buffer = try!(File::create("foo.txt")); // this call try!(write!(buffer, "{:.*}", 2, 1.234567)); // turns into this: try!(buffer.write_fmt(format_args!("{:.*}", 2, 1.234567)));
fn by_ref(&mut self) -> &mut Self where Self: Sized
Creates a "by reference" adaptor for this instance of Write
`Write`.
The returned adaptor also implements Write
`Write` and will simply borrow this
current writer.
Examples
fn main() { use std::io::Write; use std::fs::File; fn foo() -> std::io::Result<()> { let mut buffer = try!(File::create("foo.txt")); let reference = buffer.by_ref(); // we can use reference just like our original buffer try!(reference.write_all(b"some bytes")); Ok(()) } }use std::io::Write; use std::fs::File; let mut buffer = try!(File::create("foo.txt")); let reference = buffer.by_ref(); // we can use reference just like our original buffer try!(reference.write_all(b"some bytes"));
fn broadcast<W: Write>(self, other: W) -> Broadcast<Self, W> where Self: Sized
: the semantics of a partial read/write of where errors happen is currently unclear and may change
Creates a new writer which will write all data to both this writer and another writer.
All data written to the returned writer will both be written to self
`selfas well as
other. Note that the error semantics of the current implementation do not precisely track where errors happen. For example an error on the second call to
writewill not report that the first call to
write` succeeded.
Examples
#![feature(io)] fn main() { use std::io::prelude::*; use std::fs::File; fn foo() -> std::io::Result<()> { let mut buffer1 = try!(File::create("foo.txt")); let mut buffer2 = Vec::new(); // write the output to buffer1 as we read let mut handle = buffer1.broadcast(&mut buffer2); try!(handle.write(b"some bytes")); Ok(()) } }#![feature(io)] use std::io::prelude::*; use std::fs::File; let mut buffer1 = try!(File::create("foo.txt")); let mut buffer2 = Vec::new(); // write the output to buffer1 as we read let mut handle = buffer1.broadcast(&mut buffer2); try!(handle.write(b"some bytes"));
Implementors
impl Write for File
impl<'a> Write for &'a File
impl<W: Write> Write for BufWriter<W>
impl<W: Write> Write for LineWriter<W>
impl<S: Read + Write> Write for BufStream<S>
impl<'a> Write for Cursor<&'a mut [u8]>
impl Write for Cursor<Vec<u8>>
impl<'a, W: Write + ?Sized> Write for &'a mut W
impl<W: Write + ?Sized> Write for Box<W>
impl<'a> Write for &'a mut [u8]
impl Write for Vec<u8>
impl Write for Sink
impl Write for Stdout
impl<'a> Write for StdoutLock<'a>
impl Write for Stderr
impl<'a> Write for StderrLock<'a>
impl<T: Write, U: Write> Write for Broadcast<T, U>
impl Write for TcpStream
impl<'a> Write for &'a TcpStream
impl Write for ChildStdin