Trait std::io::Write1.0.0[][src]

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 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
, { ... } }
Expand description

trait 用于面向字节的 sinks 的对象。

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

Writers 由两种必需的方法 writeflush 定义:

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

  • flush 方法对于适配器和显式缓冲区本身很有用,以确保所有缓冲数据都已推送到 true 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(())
}
Run

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

Required methods

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

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

不能保证对 write 的调用会阻塞等待数据写入的等待,否则可以通过 Err 成员指示将阻塞的写入。

如果返回值为 Ok(n),则必须保证 n <= buf.len()0 的返回值通常意味着基础 object 不再能够接受字节,并且可能也无法在 future 中接收,或者提供的缓冲区为空。

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

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

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

Provided methods

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

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

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

Examples

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

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

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

    // 写入字节字符串的某些前缀,不一定要全部。
    buffer.write_vectored(&[io_slice1, io_slice2])?;
    Ok(())
}
Run
🔬 This is a nightly-only experimental API. (can_vector #69941)

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

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

默认实现返回 false

尝试将整个缓冲区写入此 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(())
}
Run
🔬 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 的所有权,并且此后不使用 bufsIoSlice 指向的基础缓冲区 (而不是 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]);
Run

将格式化的字符串写入此 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(())
}
Run

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

Implementors

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

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

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

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

🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (can_vector #69941)
This is supported on Unix only.
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (write_all_vectored #70436)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (write_all_vectored #70436)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (write_all_vectored #70436)
🔬 This is a nightly-only experimental API. (can_vector #69941)
🔬 This is a nightly-only experimental API. (write_all_vectored #70436)
This is supported on Unix only.
🔬 This is a nightly-only experimental API. (can_vector #69941)

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

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