Trait genio::Write [−] [src]

pub trait Write {
    type WriteError;
    type FlushError;
    fn write(&mut self, buf: &[u8]) -> Result<usize, Self::WriteError>;
    fn flush(&mut self) -> Result<(), Self::FlushError>;

    fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::WriteError> { ... }
    fn size_hint(&mut self, min: usize, max: Option<usize>) { ... }
}

A trait for objects which are byte-oriented sinks.

Implementors of the Write trait are sometimes called 'writers'.

Writers are defined by two required types WriteError, FlushError and methods, write() and flush():

The write() method will attempt to write some data into the object, returning how many bytes were successfully written.

The 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 genio take and provide types which implement the Write trait.

Associated Types

Value of this type is returned when write() fails.

It's highly recommended to use Void from void crate if read() can never fail.

Value of this type is returned when flush() fails. In case of low-level writers flush often does nothing and therefore doesn't return error, so this type might be Void.

It's highly recommended to use Void from void crate if read() can never fail.

Required Methods

Write a buffer into this object, returning how many bytes were written.

This function will attempt to write the entire contents of 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.

If the return value is 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 may generate an WriteError 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.

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.

Provided Methods

Attempts to write an entire buffer into this Write.

Hints the writer how much bytes will be written after call to this function. At least min bytes should be written after the call to this function and if max is Some(x) than at most x bytes should be written.

Call to this function might enable some optimizations (e.g. pre-allocating buffer of appropriate size). The implementors must not rely on this call to provide correct values or on this function being called at all! (Especially they must not cause undefined behavior.) However, performance might be arbitrarilly degraded in case min value is incorrect.

By default this function does nothing.

Implementors