Trait stylish_core::io::Write

source · [−]
pub trait Write {
    fn write(&mut self, buf: &[u8], style: Style) -> Result<usize>;
    fn flush(&mut self) -> Result<()>;

    fn write_all(&mut self, buf: &[u8], style: Style) -> Result<()> { ... }
    fn write_fmt(&mut self, args: Arguments<'_>) -> Result<()> { ... }
    fn by_ref(&mut self) -> &mut Self
   where
        Self: Sized,
    { ... }
}
Available on crate feature std only.
Expand description

A trait for objects which are byte-oriented sinks and can handle attributed data.

Writers are defined by two required 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’.

Examples

use stylish::{io::Write, Foreground, Color, Style};

let data = b"some bytes";
let style = Style::default().with(Foreground(Color::Blue));
     
let mut pos = 0;
let mut output = stylish::io::plain(std::io::stdout());

while pos < data.len() {
    let bytes_written = output.write(&data[pos..], style)?;
    pos += bytes_written;
}

output.flush()?;

Required Methods

Write a buffer into this writer with a specified style, 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, plus whatever is needed to change the style.

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 the return value is Ok(n) then it must be guaranteed that 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 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, but the writers state may have changed to match the new style (or may be in an inconsistent state if the error occurred while changing style).

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. (Note to implementors: this means you must internally retry if changing style and an Interrupted error occurs).

use stylish::{io::Write, Color, Foreground, Style};

let mut output = stylish::io::plain(std::io::stdout());

// Writes some prefix of the byte string, not necessarily all of it.
output.write(
    b"some bytes",
    Style::default().with(Foreground(Color::Blue)),
)?;

output.flush()?;

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.

use stylish::{io::Write, Color, Foreground, Style};

let mut output = stylish::io::plain(std::io::stdout());

output.write_all(
    b"some bytes",
    Style::default().with(Foreground(Color::Blue)),
)?;

output.flush()?;

Provided Methods

Attempts to write an entire buffer into this writer using a specified style.

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 stylish::{io::Write, Color, Foreground, Style};

let mut output = stylish::io::plain(std::io::stdout());

output.write_all(
    b"some bytes",
    Style::default().with(Foreground(Color::Blue)),
)?;

Writes a formatted string into this writer, returning any error encountered.

This method is primarily used to interface with the stylish::format_args! macro, but it is rare that this should explicitly be called. The stylish::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
let mut output = stylish::io::plain(std::io::stdout());

output.write_fmt(stylish::format_args!("{:(fg=red)}", '☎'))?;

Creates a “by reference” adaptor for this instance of Write.

The returned adaptor also implements Write and will simply borrow this current writer.

Examples
use stylish::{io::Write, Color, Foreground, Style};

let mut output = stylish::io::plain(std::io::stdout());

let reference = output.by_ref();

// we can use reference just like our original output
reference.write_all(
    b"some bytes",
    Style::default().with(Foreground(Color::Blue)),
)?;

Implementations on Foreign Types

Implementors