Struct std::io::BufWriter

pub struct BufWriter<W: Write> { /* private fields */ }

包装一个 writer 并缓冲其输出。

直接与实现 Write 的组件一起工作可能会非常低效。 例如，对 TcpStream 上 write 的每次调用都会导致系统调用。 BufWriter<W> 保留数据的内存缓冲区，并以大批量、不频繁的方式将其写入底层 writer。

BufWriter<W> 可以提高对同一文件或网络套接字进行小规模重复写调用的程序的速度。 一次写入大量或一次写入几次都无济于事。 在写入内存中的目标时，它也没有提供任何优势，例如 Vec<u8>.

在丢弃 BufWriter<W> 之前，调用 flush 至关重要。 尽管丢弃将尝试刷新缓冲区的内容，但丢弃过程中发生的任何错误都将被忽略。 调用 flush 可确保缓冲区为空，因此丢弃操作甚至不会尝试文件操作。

Examples

让我们将数字 1 到 10 写入 TcpStream：

use std::io::prelude::*;
use std::net::TcpStream;

let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();

for i in 0..10 {
    stream.write(&[i+1]).unwrap();
}

因为我们没有缓冲，所以我们依次写入每个字节，从而导致写入的每个字节占用系统调用的开销。我们可以用 BufWriter<W>:

use std::io::prelude::*;
use std::io::BufWriter;
use std::net::TcpStream;

let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());

for i in 0..10 {
    stream.write(&[i+1]).unwrap();
}
stream.flush().unwrap();

通过用 BufWriter<W> 包装流，这十次写操作全部由缓冲区分组，并且在刷新 stream 时将全部写在一个系统调用中。

Implementations

impl<W: Write> BufWriter<W>

pub fn new(inner: W) -> BufWriter<W>

创建一个具有默认缓冲区容量的新 BufWriter<W>。 当前默认值为 8 KB，但可能会在 future 中进行更改。

Examples

use std::io::BufWriter;
use std::net::TcpStream;

let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());

pub fn with_capacity(capacity: usize, inner: W) -> BufWriter<W>

创建一个至少具有指定缓冲区容量的新 BufWriter<W>。

Examples

创建一个缓冲区，至少有一百字节的缓冲区。

use std::io::BufWriter;
use std::net::TcpStream;

let stream = TcpStream::connect("127.0.0.1:34254").unwrap();
let mut buffer = BufWriter::with_capacity(100, stream);

pub fn get_ref(&self) -> &W

获取对底层 writer 的引用。

Examples

use std::io::BufWriter;
use std::net::TcpStream;

let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// 我们可以像缓冲区一样使用引用
let reference = buffer.get_ref();

pub fn get_mut(&mut self) -> &mut W

获取底层 writer 的可变引用。

直接写给底层的 writer 是不可取的。

Examples

use std::io::BufWriter;
use std::net::TcpStream;

let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// 我们可以像缓冲区一样使用引用
let reference = buffer.get_mut();

pub fn buffer(&self) -> &[u8]

返回对内部缓冲数据的引用。

Examples

use std::io::BufWriter;
use std::net::TcpStream;

let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// 查看当前缓冲了多少字节
let bytes_buffered = buf_writer.buffer().len();

pub fn capacity(&self) -> usize

返回内部缓冲区在不刷新的情况下可以容纳的字节数。

Examples

use std::io::BufWriter;
use std::net::TcpStream;

let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// 检查内部缓冲区的容量
let capacity = buf_writer.capacity();
// 计算不刷新就可以写入多少个字节
let without_flush = capacity - buf_writer.buffer().len();

pub fn into_inner(self) -> Result<W, IntoInnerError<BufWriter<W>>>

解包此 BufWriter<W>，返回底层 writer。

在返回 writer 之前将缓冲区写出。

Errors

如果刷新缓冲区时发生错误，将返回 Err。

Examples

use std::io::BufWriter;
use std::net::TcpStream;

let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// 拆开 TcpStream 并刷新缓冲区
let stream = buffer.into_inner().unwrap();

pub fn into_parts(self) -> (W, Result<Vec<u8>, WriterPanicked>)

反汇编这个 BufWriter<W>，返回底层 writer，以及任何缓冲但未写入的数据。

如果底层的 writer 发生 panic，就不知道数据的哪一部分被写入了。 在这种情况下，我们返回 WriterPanicked 作为缓冲数据 (仍然可以从中恢复缓冲内容)。

into_parts 不会尝试刷新数据，并且不会失败。

Examples

use std::io::{BufWriter, Write};

let mut buffer = [0u8; 10];
let mut stream = BufWriter::new(buffer.as_mut());
write!(stream, "too much data").unwrap();
stream.flush().expect_err("it doesn't fit");
let (recovered_writer, buffered_data) = stream.into_parts();
assert_eq!(recovered_writer.len(), 0);
assert_eq!(&buffered_data.unwrap(), b"ata");

Trait Implementations

impl<W> Debug for BufWriter<W>where W: Debug + Write,

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

使用给定的格式化程序格式化该值。

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

fn drop(&mut self)

执行此类型的析构函数。

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

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

寻找底层 writer 中的偏移量（以字节为单位）。

寻找总是在寻找之前写出内部缓冲区。

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

返回到流的开头。

fn stream_len(&mut self) -> Result<u64>

🔬This is a nightly-only experimental API. (seek_stream_len #59359)

返回此流的长度 (以字节为单位)。

fn stream_position(&mut self) -> Result<u64>

从流的开头返回当前查找位置。

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

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

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

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

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

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

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

fn is_write_vectored(&self) -> bool

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

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

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

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

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

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

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

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

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

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

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