1.0.0[−][src]Trait gnverify::io::prelude::Write

pub trait Write {
    fn write(&mut self, buf: &[u8]) -> Result<usize, Error>;

    fn flush(&mut self) -> Result<(), Error>;

    fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize, Error> { ... }

    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 { ... }
}

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 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 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

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 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 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.

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(())
}

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(())
}
Loading content...

Provided methods

fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize, Error>1.36.0

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.

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(())
}

fn write_all_vectored(&mut self, bufs: &mut [IoSlice]) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (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 io::Write::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]);

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, but 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(())
}

fn by_ref(&mut self) -> &mut Self

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 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(())
}
Loading content...

Implementations on Foreign Types

impl Write for Vec<u8>[src]

Write is implemented for Vec<u8> by appending to the vector. The vector will grow as needed.

impl<W> Write for Box<W> where
    W: Write + ?Sized, [src]

impl Write for File[src]

impl Write for TcpStream[src]

impl<'_> Write for &'_ mut [u8][src]

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.

impl Write for ChildStdin[src]

impl<'_> Write for &'_ File[src]

impl<'_, W> Write for &'_ mut W where
    W: Write + ?Sized, [src]

impl<'_> Write for &'_ TcpStream[src]

impl<'a, W> Write for EncoderWriter<'a, W> where
    W: Write, 

fn write(&mut self, input: &[u8]) -> Result<usize, Error>

Encode input and then write to the delegate writer.

Under non-error circumstances, this returns Ok with the value being the number of bytes of input consumed. The value may be 0, which interacts poorly with write_all, which interprets Ok(0) as an error, despite it being allowed by the contract of write. See https://github.com/rust-lang/rust/issues/56889 for more on that.

If the previous call to write provided more (encoded) data than the delegate writer could accept in a single call to its write, the remaining data is buffered. As long as buffered data is present, subsequent calls to write will try to write the remaining buffered data to the delegate and return either Ok(0) -- and therefore not consume any of input -- or an error.

Errors

Any errors emitted by the delegate writer are returned.

fn flush(&mut self) -> Result<(), Error>

Because this is usually treated as OK to call multiple times, it will not flush any incomplete chunks of input or write padding.

impl<B> Write for Writer<B> where
    B: BufMut, [src]

impl<L, R> Write for Either<L, R> where
    L: Write,
    R: Write, [src]

Either<L, R> implements Write if both L and R do.

Requires crate feature "use_std"

impl Write for AddrStream[src]

impl Write for Upgraded[src]

impl<T> Write for AllowStdIo<T> where
    T: Write, [src]

impl<T> Write for WriteHalf<T> where
    T: AsyncWrite, [src]

impl Write for TcpStream[src]

impl<'a> Write for &'a TcpStream[src]

impl<'a> Write for &'a AnonWrite[src]

impl<'a> Write for &'a NamedPipe[src]

impl Write for NamedPipe[src]

impl Write for AnonWrite[src]

impl<E> Write for PollEvented<E> where
    E: Evented + Write, [src]

impl<'a, E> Write for &'a PollEvented<E> where
    E: Evented,
    &'a E: Write, [src]

impl<A> Write for SmallVec<A> where
    A: Array<Item = u8>, 

impl Write for TcpStream[src]

impl<'a> Write for &'a TcpStream[src]

impl<T> Write for TlsStream<T> where
    T: Read + Write, [src]

impl<T> Write for MaybeHttpsStream<T> where
    T: Read + Write, [src]

impl<S> Write for TlsStream<S> where
    S: Read + Write, [src]

impl<S> Write for TlsStream<S> where
    S: Read + Write, 

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

In the case of a WouldBlock error, we expect another call starting with the same input data This is similar to the use of ACCEPT_MOVING_WRITE_BUFFER in openssl

impl<R> Write for GzEncoder<R> where
    R: Write + BufRead, [src]

impl<R> Write for MultiGzDecoder<R> where
    R: Read + Write, [src]

impl<R> Write for GzEncoder<R> where
    R: Read + Write, [src]

impl<R> Write for MultiGzDecoder<R> where
    R: Write + BufRead, [src]

impl<W> Write for ZlibEncoder<W> where
    W: Write, [src]

impl<W> Write for ZlibEncoder<W> where
    W: Read + Write, [src]

impl<R> Write for ZlibDecoder<R> where
    R: Write + BufRead, [src]

impl<W> Write for DeflateDecoder<W> where
    W: Read + Write, [src]

impl<W> Write for GzDecoder<W> where
    W: Write, [src]

impl<W> Write for ZlibDecoder<W> where
    W: Write, [src]

impl<W> Write for GzEncoder<W> where
    W: Write, [src]

impl<W> Write for DeflateEncoder<W> where
    W: Write + BufRead, [src]

impl<R> Write for ZlibEncoder<R> where
    R: Write + BufRead, [src]

impl<W> Write for CrcWriter<W> where
    W: Write, [src]

impl<R> Write for ZlibDecoder<R> where
    R: Read + Write, [src]

impl<W> Write for DeflateEncoder<W> where
    W: Write, [src]

impl<W> Write for DeflateDecoder<W> where
    W: Write, [src]

impl<R> Write for GzDecoder<R> where
    R: Write + BufRead, [src]

impl<W> Write for DeflateEncoder<W> where
    W: Read + Write, [src]

impl<R> Write for GzDecoder<R> where
    R: Read + Write, [src]

impl<W> Write for DeflateDecoder<W> where
    W: Write + BufRead, [src]

impl<W> Write for NoColor<W> where
    W: Write, 

impl Write for Buffer

impl Write for StandardStream

impl<'a> Write for StandardStreamLock<'a>

impl<W> Write for Ansi<W> where
    W: Write, 

impl Write for BufferedStandardStream

Loading content...

Implementors

impl Write for Cursor<Box<[u8]>>[src]

impl Write for Cursor<Vec<u8>>[src]

impl Write for Sink[src]

impl Write for Stderr[src]

impl Write for Stdout[src]

impl<'_> Write for Cursor<&'_ mut Vec<u8>>[src]

impl<'_> Write for Cursor<&'_ mut [u8]>[src]

impl<'_> Write for StderrLock<'_>[src]

impl<'_> Write for StdoutLock<'_>[src]

impl<W> Write for BufWriter<W> where
    W: Write, [src]

impl<W> Write for LineWriter<W> where
    W: Write, [src]

Loading content...