Struct std::io::BufWriter

1.0.0 · source ·
pub struct BufWriter<W: Write> { /* private fields */ }
Expand description

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

直接与实现 Write 的组件一起工作可能会非常低效。 例如,对 TcpStreamwrite 的每次调用都会导致系统调用。 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();
}
Run

因为我们没有缓冲,所以我们依次写入每个字节,从而导致写入的每个字节占用系统调用的开销。我们可以用 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();
Run

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

Implementations§

source§

impl<W: Write> BufWriter<W>

source

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());
Run
source

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);
Run
source

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();
Run
source

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();
Run
1.37.0 · source

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();
Run
1.46.0 · source

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();
Run
source

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();
Run
1.56.0 · source

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");
Run

Trait Implementations§

source§

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

source§

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

使用给定的格式化程序格式化该值。 Read more
source§

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

source§

fn drop(&mut self)

执行此类型的析构函数。 Read more
source§

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

source§

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

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

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

1.55.0 · source§

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

返回到流的开头。 Read more
source§

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

🔬This is a nightly-only experimental API. (seek_stream_len #59359)
返回此流的长度 (以字节为单位)。 Read more
1.51.0 · source§

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

从流的开头返回当前查找位置。 Read more
source§

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

source§

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

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

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

尝试将整个缓冲区写入此 writer。 Read more
source§

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

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

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector #69941)
确定此 Writer 是否具有有效的 write_vectored 实现。 Read more
source§

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

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

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

🔬This is a nightly-only experimental API. (write_all_vectored #70436)
尝试将多个缓冲区写入此 writer。 Read more
source§

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

将格式化的字符串写入此 writer,返回遇到的任何错误。 Read more
source§

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

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

Auto Trait Implementations§

§

impl<W> RefUnwindSafe for BufWriter<W>where W: RefUnwindSafe,

§

impl<W> Send for BufWriter<W>where W: Send,

§

impl<W> Sync for BufWriter<W>where W: Sync,

§

impl<W> Unpin for BufWriter<W>where W: Unpin,

§

impl<W> UnwindSafe for BufWriter<W>where W: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

获取 selfTypeIdRead more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

从拥有的值中一成不变地借用。 Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

从拥有的值中借用。 Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

返回未更改的参数。

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

调用 U::from(self)

也就是说,这种转换是 From<T> for U 实现选择执行的任何操作。

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

发生转换错误时返回的类型。
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

执行转换。
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

发生转换错误时返回的类型。
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

执行转换。