std::io::Write - Rust
Description: API documentation for the Rust `Write` trait in crate `std`.
Keywords: rust, rustlang, rust-lang, Write

# 1.0.0[−][src]Trait std::io::Write

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

        fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize> { ... }
        fn write_all(&mut self, buf: &[u8]) -> Result<()> { ... }
        fn write_fmt(&mut self, fmt: Arguments) -> Result<()> { ... }
        fn by_ref(&mut self) -> &mut Self
        where
            Self: Sized,
        { ... }
    }

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

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

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

### `fn flush(&mut self) -> Result<()>`

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

Loading content...

## Provided methods

### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`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<()>`

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.

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

### `fn write_fmt(&mut self, fmt: Arguments) -> Result<()>`

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

###
ⓘImportant traits for &'_ mut I

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<'_, R: Read + ?Sized> Read for &'_ mut Rimpl<'_, W: Write + ?Sized> Write for &'_ mut W`
`fn by_ref(&mut self) -> &mut Self where
Self: Sized,`

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

Loading content...

## Implementors

### `impl Write for File`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

### `impl Write for Sink`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

### `impl Write for Stderr`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

#### `fn write_all(&mut self, buf: &[u8]) -> Result<()>`[src]

#### `fn write_fmt(&mut self, args: Arguments) -> Result<()>`[src]

### `impl Write for Stdout`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

#### `fn write_all(&mut self, buf: &[u8]) -> Result<()>`[src]

#### `fn write_fmt(&mut self, args: Arguments) -> Result<()>`[src]

### `impl Write for TcpStream`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

### `impl Write for UnixStream`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

### `impl Write for ChildStdin`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

### `impl Write for Vec<u8>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn write_all(&mut self, buf: &[u8]) -> Result<()>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[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.

#### `fn write(&mut self, data: &[u8]) -> Result<usize>`[src]

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn write_all(&mut self, data: &[u8]) -> Result<()>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

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

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

#### `fn write_all(&mut self, buf: &[u8]) -> Result<()>`[src]

#### `fn write_fmt(&mut self, fmt: Arguments) -> Result<()>`[src]

### `impl<'a> Write for &'a UnixStream`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

### `impl<W: Write + ?Sized> Write for Box<W>`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

#### `fn write_all(&mut self, buf: &[u8]) -> Result<()>`[src]

#### `fn write_fmt(&mut self, fmt: Arguments) -> Result<()>`[src]

### `impl<W: Write> Write for BufWriter<W>`[src]

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

#### `fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize>`[src]

#### `fn flush(&mut self) -> Result<()>`[src]

### `impl<W: Write> Write for LineWriter<W>`[src]

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

#### `fn flush(&mut self) -> Result<()>`[src]

Loading content...