Struct std::io::BufWriter

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

包装一个 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_raw_parts(self) -> (W, Result<Vec<u8>, WriterPanicked>)

🔬 This is a nightly-only experimental API. (bufwriter_into_raw_parts #80690)

反汇编此 BufWriter<W>，返回基础 writer，以及所有缓冲但未写入的数据。

如果基础 writer 恐慌，则不知道写入了数据的哪一部分。 在这种情况下，我们返回 WriterPanicked 作为缓冲数据 (仍然可以从中恢复缓冲内容)。

into_raw_parts 不尝试刷新数据，也不会失败。

Examples

#![feature(bufwriter_into_raw_parts)]
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_raw_parts();
assert_eq!(recovered_writer.len(), 0);
assert_eq!(&buffered_data.unwrap(), b"ata");

Trait Implementations

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

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 Self where
    Self: Sized, 

为此 Write 实例创建 “by reference” 适配器。