Trait floresta_common::prelude::Write
1.0.0 · source · pub trait Write {
// Required methods
fn write(&mut self, buf: &[u8]) -> Result<usize, Error>;
fn flush(&mut self) -> Result<(), Error>;
// Provided methods
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error> { ... }
fn is_write_vectored(&self) -> bool { ... }
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error> { ... }
fn write_all_vectored(
&mut self,
bufs: &mut [IoSlice<'_>]
) -> Result<(), Error> { ... }
fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error> { ... }
fn by_ref(&mut self) -> &mut Self
where Self: Sized { ... }
}Expand description
A trait for objects which are byte-oriented sinks.
Implementors of the Write trait are sometimes called ‘writers’.
Writers are defined by two required methods, write and flush:
-
The
writemethod will attempt to write some data into the object, returning how many bytes were successfully written. -
The
flushmethod is useful for adapters 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 take and provide types which implement the Write
trait.
Examples
use std::io::prelude::*;
use std::fs::File;
fn main() -> std::io::Result<()> {
let data = b"some bytes";
let mut pos = 0;
let mut buffer = File::create("foo.txt")?;
while pos < data.len() {
let bytes_written = buffer.write(&data[pos..])?;
pos += bytes_written;
}
Ok(())
}The trait also provides convenience methods like write_all, which calls
write in a loop until its entire input has been written.
Required Methods§
sourcefn write(&mut self, buf: &[u8]) -> Result<usize, Error>
fn write(&mut self, buf: &[u8]) -> Result<usize, Error>
Write a buffer into this writer, returning how many bytes were written.
This function will attempt to write the entire contents of buf, but
the entire write might not succeed, or the write may also generate an
error. Typically, a call to write represents one attempt to write to
any wrapped object.
Calls to write are 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 this method consumed n > 0 bytes of buf it must return Ok(n).
If the return value is Ok(n) then n must satisfy n <= buf.len().
A return value of Ok(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 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.
An error of the ErrorKind::Interrupted kind is non-fatal and the
write operation should be retried if there is nothing else to do.
Examples
use std::io::prelude::*;
use std::fs::File;
fn main() -> std::io::Result<()> {
let mut buffer = File::create("foo.txt")?;
// Writes some prefix of the byte string, not necessarily all of it.
buffer.write(b"some bytes")?;
Ok(())
}sourcefn flush(&mut self) -> Result<(), Error>
fn flush(&mut self) -> Result<(), Error>
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
use std::io::prelude::*;
use std::io::BufWriter;
use std::fs::File;
fn main() -> std::io::Result<()> {
let mut buffer = BufWriter::new(File::create("foo.txt")?);
buffer.write_all(b"some bytes")?;
buffer.flush()?;
Ok(())
}Provided Methods§
1.36.0 · sourcefn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>
Like write, except that it writes from a slice of buffers.
Data is copied from each buffer in order, with the final buffer
read from possibly being only partially consumed. This method must
behave as a call to write with the buffers concatenated would.
The default implementation calls write with either the first nonempty
buffer provided, or an empty one if none exists.
Examples
use std::io::IoSlice;
use std::io::prelude::*;
use std::fs::File;
fn main() -> std::io::Result<()> {
let data1 = [1; 8];
let data2 = [15; 8];
let io_slice1 = IoSlice::new(&data1);
let io_slice2 = IoSlice::new(&data2);
let mut buffer = File::create("foo.txt")?;
// Writes some prefix of the byte string, not necessarily all of it.
buffer.write_vectored(&[io_slice1, io_slice2])?;
Ok(())
}sourcefn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector)Determines if this Writer has an efficient write_vectored
implementation.
If a Writer does not override the default write_vectored
implementation, code using it may want to avoid the method all together
and coalesce writes into a single buffer for higher performance.
The default implementation returns false.
sourcefn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
Attempts to write an entire buffer into this writer.
This method will continuously call write until there is no more data
to be written or an error of non-ErrorKind::Interrupted kind is
returned. This method will not return until the entire buffer has been
successfully written or such an error occurs. The first error that is
not of ErrorKind::Interrupted kind generated from this method will be
returned.
If the buffer contains no data, this will never call write.
Errors
This function will return the first error of
non-ErrorKind::Interrupted kind that write returns.
Examples
use std::io::prelude::*;
use std::fs::File;
fn main() -> std::io::Result<()> {
let mut buffer = File::create("foo.txt")?;
buffer.write_all(b"some bytes")?;
Ok(())
}sourcefn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored)Attempts to write multiple buffers into this writer.
This method will continuously call write_vectored until there is no
more data to be written or an error of non-ErrorKind::Interrupted
kind is returned. This method will not return until all buffers have
been successfully written or such an error occurs. The first error that
is not of ErrorKind::Interrupted kind generated from this method
will be returned.
If the buffer contains no data, this will never call write_vectored.
Notes
Unlike write_vectored, this takes a mutable reference to
a slice of IoSlices, not an immutable one. That’s because we need to
modify the slice to keep track of the bytes already written.
Once this function returns, the contents of bufs are unspecified, as
this depends on how many calls to write_vectored were necessary. It is
best to understand this function as taking ownership of bufs and to
not use bufs afterwards. The underlying buffers, to which the
IoSlices point (but not the IoSlices themselves), are unchanged and
can be reused.
Examples
#![feature(write_all_vectored)]
use std::io::{Write, IoSlice};
let mut writer = Vec::new();
let bufs = &mut [
IoSlice::new(&[1]),
IoSlice::new(&[2, 3]),
IoSlice::new(&[4, 5, 6]),
];
writer.write_all_vectored(bufs)?;
// Note: the contents of `bufs` is now undefined, see the Notes section.
assert_eq!(writer, &[1, 2, 3, 4, 5, 6]);sourcefn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>
fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>
Writes a formatted string into this writer, returning any error encountered.
This method is primarily used to interface with the
format_args!() macro, and it is rare that this should
explicitly be called. The 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
use std::io::prelude::*;
use std::fs::File;
fn main() -> std::io::Result<()> {
let mut buffer = File::create("foo.txt")?;
// this call
write!(buffer, "{:.*}", 2, 1.234567)?;
// turns into this:
buffer.write_fmt(format_args!("{:.*}", 2, 1.234567))?;
Ok(())
}sourcefn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere Self: Sized,
Creates a “by reference” adapter for this instance of Write.
The returned adapter also implements Write and will simply borrow this
current writer.
Examples
use std::io::Write;
use std::fs::File;
fn main() -> std::io::Result<()> {
let mut buffer = File::create("foo.txt")?;
let reference = buffer.by_ref();
// we can use reference just like our original buffer
reference.write_all(b"some bytes")?;
Ok(())
}Implementors§
impl Write for &File
impl Write for &Stderr
impl Write for &Stdout
impl Write for &Empty
impl Write for &Sink
impl Write for &TcpStream
impl Write for &ChildStdin
impl Write for &mut [u8]
Write is implemented for &mut [u8] by copying into the slice, overwriting
its data.
Note that writing updates the slice to point to the yet unwritten part. The slice will be empty when it has been completely overwritten.
If the number of bytes to be written exceeds the size of the slice, write operations will
return short writes: ultimately, Ok(0); in this situation, write_all returns an error of
kind ErrorKind::WriteZero.
impl Write for bitcoin_hashes::ripemd160::HashEngine
impl Write for bitcoin_hashes::sha1::HashEngine
impl Write for bitcoin_hashes::sha256::HashEngine
impl Write for bitcoin_hashes::sha512::HashEngine
impl Write for bitcoin_hashes::siphash24::HashEngine
impl Write for File
impl Write for Cursor<&mut [u8]>
impl Write for Stderr
impl Write for StderrLock<'_>
impl Write for Stdout
impl Write for StdoutLock<'_>
impl Write for Empty
impl Write for Sink
impl Write for TcpStream
impl Write for UnixStream
impl Write for ChildStdin
impl Write for Arc<File, Global>
impl<'a> Write for &'a UnixStream
impl<'a> Write for BorrowedCursor<'a>
impl<A> Write for VecDeque<u8, A>where A: Allocator,
Write is implemented for VecDeque<u8> by appending to the VecDeque, growing it as needed.
impl<A> Write for Cursor<&mut Vec<u8, A>>where A: Allocator,
impl<A> Write for Cursor<Box<[u8], A>>where A: Allocator,
impl<A> Write for Cursor<Vec<u8, A>>where A: Allocator,
impl<A> Write for Vec<u8, A>where A: Allocator,
Write is implemented for Vec<u8> by appending to the vector.
The vector will grow as needed.