[−][src]Trait genio::Write

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 size_hint(&mut self, bytes: usize);

    fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::WriteError> { ... }
    fn uses_size_hint(&self) -> bool { ... }
}

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

`type WriteError`

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

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

`type FlushError`

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.

Loading content...

Required methods

`fn write(&mut self, buf: &[u8]) -> Result<usize, Self::WriteError>`

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.

`fn flush(&mut self) -> Result<(), Self::FlushError>`

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.

`fn size_hint(&mut self, bytes: usize)`

Hints the writer how much bytes will be written after call to this function. If the maximum amount of bytes to be written is known then it should be passed as argument. If the maximum amount is unknown, then minimum should be passed.

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 caller provides wrong value.

The function is mandatory, as a lint to incentivize implementors to implement it, if applicable. Note that if you implement this function, you must also implement uses_size_hint.

Loading content...