Trait std::io::Write 1.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 由两种必需的方法 write 和 flush 定义:
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
fn is_write_vectored(&self) -> bool
[src]
fn is_write_vectored(&self) -> bool
[src]确定此 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
尝试将多个缓冲区写入此 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]);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
Implementors
通过将 &mut [u8] 复制到切片中并覆盖其数据来实现写入。
请注意，编写会更新切片以指向尚未编写的部分。 完全覆盖后，切片将为空。
如果要写入的字节数超过了切片的大小，则写入操作将返回短写入: 最终为 Ok(0); 否则为 Ok(0)。在这种情况下，write_all 返回类型为 ErrorKind::WriteZero 的错误。
通过将 Vec<u8> 附加到 vector 来实现写操作。
vector 将根据需要增长。