Trait std::io::Write

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

    // Provided methods
    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize> { ... }
    fn is_write_vectored(&self) -> bool { ... }
    fn write_all(&mut self, buf: &[u8]) -> Result<()> { ... }
    fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()> { ... }
    fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()> { ... }
    fn by_ref(&mut self) -> &mut Self
       where Self: Sized { ... }
}

面向字节的接收器对象的 trait。

Write trait 的实现者有时称为 ‘writers’。

Writers 由两种必需的方法 write 和 flush 定义：

• write 方法将尝试将一些数据写入对象，返回成功写入的字节数。

• flush 方法对于适配器和显式缓冲区本身很有用，以确保所有缓冲数据都已被推送到 真正的 sink。

Writers 旨在彼此组成。 std::io 上的许多实现器都采用并提供实现 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(())
}

这个 trait 还提供了便捷的方法，例如 write_all，它在循环中调用 write，直到其整个输入都被写入为止。

Required Methods

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

在此 writer 中写入一个缓冲区，返回写入的字节数。

这个函数会尝试写入 buf 的全部内容，但是整个写入可能不会成功，或者写入也会产生错误。 对 write 的调用表示 *at most 对任何包装的对象进行写操作的尝试。

不能保证对 write 的调用会阻塞等待数据的写入，否则可以通过 Err 变体指示被阻塞的写入。

如果返回值为 Ok(n)，则必须保证 n <= buf.len()。 返回值 0 通常意味着底层对象不再能够接受字节，并且将来也可能无法接受，或者提供的缓冲区为空。

Errors

对 write 的每次调用都可能产生 I/O 错误，指示操作无法完成。如果返回错误，则缓冲区中没有字节写入此 writer。

如果无法将整个缓冲区写入此 writer，则不认为是错误。

ErrorKind::Interrupted 类型的错误是非致命错误，如果没有其他事情可做，则应重试写入操作。

Examples

use std::io::prelude::*;
use std::fs::File;

fn main() -> std::io::Result<()> {
    let mut buffer = File::create("foo.txt")?;

    // 写入字节字符串的某些前缀，不一定要全部。
    buffer.write(b"some bytes")?;
    Ok(())
}

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

刷新此输出流，确保所有中间缓冲的内容均到达其目的地。

Errors

如果由于 I/O 错误或达到 EOF 而无法写入所有字节，则认为是错误。

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

Provided Methods

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

类似于 write，不同之处在于它是从缓冲区切片中写入数据的。

数据是按顺序从每个缓冲区复制的，从中读取的最终缓冲区可能仅被部分消耗。 此方法必须与串联的缓冲区对 write 的调用相同。

默认实现使用提供的第一个非空缓冲区调用 write，如果不存在，则为空。

Examples

use std::io::IoSlice;
use std::io::prelude::*;
use std::fs::File;

fn main() -> std::io::Result<()> {
    let data1 = [1; 8];
    let data2 = [15; 8];
    let io_slice1 = IoSlice::new(&data1);
    let io_slice2 = IoSlice::new(&data2);

    let mut buffer = File::create("foo.txt")?;

    // 写入字节字符串的某些前缀，不一定要全部。
    buffer.write_vectored(&[io_slice1, io_slice2])?;
    Ok(())
}

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector #69941)

确定此 Writer 是否具有有效的 write_vectored 实现。

如果 Writer 没有覆盖默认的 write_vectored 实现，则使用它的代码可能希望完全避免使用该方法，并合并写入单个缓冲区以提高性能。

默认实现返回 false。

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

尝试将整个缓冲区写入此 writer。

此方法将连续调用 write，直到没有更多数据要写入或返回非 ErrorKind::Interrupted 类型的错误为止。 在成功写入整个缓冲区或发生此类错误之前，此方法将不会返回。 从此方法生成的不是 ErrorKind::Interrupted 类型的第一个错误将被返回。

如果缓冲区不包含任何数据，则永远不会调用 write。

Errors

该函数将返回 write 返回的第一个非 -ErrorKind::Interrupted 类型的错误。

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

🔬This is a nightly-only experimental API. (write_all_vectored #70436)

尝试将多个缓冲区写入此 writer。

此方法将连续调用 write_vectored，直到没有更多数据要写入或返回非 ErrorKind::Interrupted 类型的错误为止。

在成功写入所有缓冲区或发生此类错误之前，此方法将不会返回。 从此方法生成的不是 ErrorKind::Interrupted 类型的第一个错误将被返回。

如果缓冲区不包含任何数据，则永远不会调用 write_vectored。

Notes

与 write_vectored 不同，这需要对 IoSlice 的切片进行 可变 引用，而不是不可变。 那是因为我们需要修改切片以跟踪已写入的字节。

此函数返回后，将不指定 bufs 的内容，这取决于需要对 write_vectored 进行多少次调用。 最好将此函数理解为拥有 bufs 的所有权，并且此后不使用 bufs。 IoSlice 指向的底层缓冲区 (而不是 IoSlice 本身) 是不变的，可以重用。

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: `bufs` 的内容现在是不确定的，请参见说明部分。

assert_eq!(writer, &[1, 2, 3, 4, 5, 6]);

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

将格式化的字符串写入此 writer，返回遇到的任何错误。

此方法主要用于与 format_args!() 宏接口，很少需要显式调用。 应优先使用 write!() 宏来调用此方法。

此函数内部在此 trait 上使用 write_all 方法，因此只要没有收到错误，就将连续写入数据。

这也意味着此签名中未指示部分写入。

Errors

此函数将返回格式化时报告的任何 I/O 错误。

Examples

use std::io::prelude::*;
use std::fs::File;

fn main() -> std::io::Result<()> {
    let mut buffer = File::create("foo.txt")?;

    // 这个
    write!(buffer, "{:.*}", 2, 1.234567)?;
    // 变成这样：
    buffer.write_fmt(format_args!("{:.*}", 2, 1.234567))?;
    Ok(())
}

fn by_ref(&mut self) -> &mut Selfwhere Self: Sized,

为这个 Write 实例创建一个 “by reference” 适配器。

返回的适配器也实现了 Write，并将简单地借用当前的 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();

    // 我们可以像使用原始缓冲区一样使用引用
    reference.write_all(b"some bytes")?;
    Ok(())
}

Implementors

impl Write for &File

impl Write for &TcpStream

impl Write for &ChildStdin

impl Write for &Sink

impl Write for &Stderr

impl Write for &Stdout

impl Write for &mut [u8]

通过将 &mut [u8] 复制到切片中并覆盖其数据来实现写入。

请注意，编写会更新切片以指向尚未编写的部分。 完全覆盖后，切片将为空。

如果要写入的字节数超过了切片的大小，则写入操作将返回短写入：最终为 Ok(0); 否则为 Ok(0)。在这种情况下，write_all 返回类型为 ErrorKind::WriteZero 的错误。

impl Write for File

impl Write for TcpStream

impl Write for UnixStream

Available on Unix only.

impl Write for ChildStdin

impl Write for Cursor<&mut [u8]>

impl Write for Sink

impl Write for Stderr

impl Write for StderrLock<'_>

impl Write for Stdout

impl Write for StdoutLock<'_>

impl<'a> Write for &'a UnixStream

Available on Unix only.

impl<'a> Write for BorrowedCursor<'a>

impl<A> Write for Cursor<&mut Vec<u8, A>>where A: Allocator,

impl<A> Write for Cursor<Box<[u8], A>>where A: Allocator,

impl<A> Write for Cursor<Vec<u8, A>>where A: Allocator,

impl<A: Allocator> Write for VecDeque<u8, A>

通过，追加，到 VecDeque 来实现 VecDeque<u8> 的写入，并根据需要对其进行扩展。

impl<A: Allocator> Write for Vec<u8, A>

通过将 Vec<u8> 追加到 vector 来实现写入操作。 vector 将根据需要增长。

impl<W: Write + ?Sized> Write for &mut W

impl<W: Write + ?Sized> Write for Box<W>

impl<W: Write> Write for BufWriter<W>

impl<W: Write> Write for LineWriter<W>

impl<const N: usize> Write for Cursor<[u8; N]>