Module std::io

core I/O 功能的 Traits，助手和类型定义。

std::io 模块包含许多在执行输入和输出时需要的常见操作。 该模块中最 core 的部分是 Read 和 Write traits，它们提供用于读取和写入输入和输出的最通用接口。

读和写

因为它们是 traits，所以 Read 和 Write 由许多其他类型实现，您也可以为您的类型实现它们。 这样，您将在此模块的整个文档中看到几种不同类型的 I/O: File，TcpStream，有时甚至是 Vec<T>。 例如，Read 添加了 read 方法，我们可以在 File 上使用该方法:

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

fn main() -> io::Result<()> {
    let mut f = File::open("foo.txt")?;
    let mut buffer = [0; 10];

    // 最多读取 10 个字节
    let n = f.read(&mut buffer)?;

    println!("The bytes: {:?}", &buffer[..n]);
    Ok(())
}

Read 和 Write 非常重要，两个 traits 的实现者都有一个昵称: readers 和 writers。 因此，有时您会看到 reader 而不是 实现 [Read] trait 的类型。 容易得多!

Seek 和 BufRead

除此之外，还提供了两个重要的 traits: Seek 和 BufRead。两者都建立在 reader 的顶部，以控制读取的方式。 Seek 让您控制下一个字节的来源:

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

fn main() -> io::Result<()> {
    let mut f = File::open("foo.txt")?;
    let mut buffer = [0; 10];

    // 跳到文件的最后 10 个字节
    f.seek(SeekFrom::End(-10))?;

    // 最多读取 10 个字节
    let n = f.read(&mut buffer)?;

    println!("The bytes: {:?}", &buffer[..n]);
    Ok(())
}

BufRead 使用内部缓冲区来提供许多其他读取方式，但是为了展示它，我们通常需要讨论缓冲区。继续阅读!

BufReader 和 BufWriter

基于字节的接口笨拙且效率低下，因为我们需要对操作系统进行近乎恒定的调用。 为了解决这个问题，std::io 带有两个结构体 BufReader 和 BufWriter，它们包装了 readers 和 writers。 包装器使用缓冲区，从而减少了调用次数，并提供了更好的方法来访问所需的内容。

例如，BufReader 与 BufRead trait 一起为任何 reader 添加额外的方法:

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

fn main() -> io::Result<()> {
    let f = File::open("foo.txt")?;
    let mut reader = BufReader::new(f);
    let mut buffer = String::new();

    // 将一行读入缓冲区
    reader.read_line(&mut buffer)?;

    println!("{}", buffer);
    Ok(())
}

BufWriter 没有添加任何新的写作方式; 它只是缓冲每个调用到 write:

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

fn main() -> io::Result<()> {
    let f = File::create("foo.txt")?;
    {
        let mut writer = BufWriter::new(f);

        // 向缓冲区写入一个字节
        writer.write(&[42])?;

    } // writer 离开作用域后，将刷新缓冲区

    Ok(())
}

标准输入输出

输入的一个非常常见的来源是标准输入:

use std::io;

fn main() -> io::Result<()> {
    let mut input = String::new();

    io::stdin().read_line(&mut input)?;

    println!("You typed: {}", input.trim());
    Ok(())
}

请注意，不能在不返回 Result<T, E> 的函数中使用 ? operator。 相反，您可以在返回值上调用 .unwrap() 或 match 来捕获任何可能的错误:

use std::io;

let mut input = String::new();

io::stdin().read_line(&mut input).unwrap();

标准输出是一个非常常见的输出源:

use std::io;
use std::io::prelude::*;

fn main() -> io::Result<()> {
    io::stdout().write(&[42])?;
    Ok(())
}

当然，直接使用 io::stdout 比使用 println! 少见。

迭代器类型

std::io 提供的大量结构用于在 I/O 上进行迭代的各种方式。例如，Lines 用于拆分多行:

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

fn main() -> io::Result<()> {
    let f = File::open("foo.txt")?;
    let reader = BufReader::new(f);

    for line in reader.lines() {
        println!("{}", line?);
    }
    Ok(())
}

Functions

有许多 函数 提供对各种功能的访问。 例如，我们可以使用以下三个函数将所有内容从标准输入复制到标准输出:

use std::io;

fn main() -> io::Result<()> {
    io::copy(&mut io::stdin(), &mut io::stdout())?;
    Ok(())
}

io::Result

最后但并非最不重要的是 io::Result。 此类型用作许多 std::io 函数的返回类型，它们可能导致错误，也可以从您自己的函数中返回。 该模块中的许多示例都使用 ? operator:

use std::io;

fn read_input() -> io::Result<()> {
    let mut input = String::new();

    io::stdin().read_line(&mut input)?;

    println!("You typed: {}", input.trim());

    Ok(())
}

read_input() 的返回类型 io::Result<()> 是函数的一种非常常见的类型，它没有 ‘real’ 返回值，但是希望在发生错误时返回错误。

在这种情况下，此函数的唯一目的是读取并打印该行，因此我们使用 ()。

平台特定的行为

记录了整个标准库中的许多 I/O 函数，以指示将它们委派给的各种库或 syscall。 这样做是为了帮助应用程序了解幕后的情况以及调查任何可能不清楚的语义。 但是请注意，这只是提供信息，而不是有约束力的契约。 其中许多函数的实现会随时间而变化，并且可能调用更少或更多的 syscalls/library 函数。

Modules

prelude

I/O Prelude。

Structs

Initializer	Experimental 一种类型，用于有条件地初始化传递给 Read 方法的缓冲区。
BufReader	BufReader<R> 结构体将缓冲添加到任何 reader。
BufWriter	包装一个 writer 并缓冲其输出。
Bytes	reader 的 u8 值上的迭代器。
Chain	将两个 readers 链接在一起的适配器。
Cursor	Cursor 包装内存中的缓冲区，并为其提供 Seek 实现。
Empty	始终处于 EOF 的 reader。
Error	Read，Write，Seek 和关联的 traits 的 I/O 操作的错误类型。
IntoInnerError	BufWriter::into_inner 返回的错误，将写出缓冲区时发生的错误与缓冲的 writer object 结合在一起，可用于从条件中恢复。
IoSlice	Write::write_vectored 使用的缓冲区类型。
IoSliceMut	Read::read_vectored 使用的缓冲区类型。
LineWriter	包装一个 writer 并缓冲输出到它的内容，每当检测到换行符 (0x0a，‘\n’`) 时刷新一次。
Lines	BufRead 实例的行上的迭代器。
Repeat	一个 reader，一个又一个的字节，一个又一个的字节，一个又一个的字节。
Sink	一个 writer，它将数据移入无效空间。
Split	对 BufRead 实例的内容进行迭代的迭代器，该实例在特定字节上拆分。
Stderr	进程的标准错误流的句柄。
StderrLock	Stderr 句柄的锁定引用。
Stdin	进程的标准输入流的句柄。
StdinLock	Stdin 句柄的锁定引用。
Stdout	当前进程的标准输出流的句柄。
StdoutLock	Stdout 句柄的锁定引用。
Take	Reader 适配器，用于限制从基础 reader 读取的字节。

Enums

ErrorKind	一个列表，指定 I/O 错误的常规类别。
SeekFrom	列举可能在 I/O object 中进行搜索的方法。

Traits

BufRead	BufRead 是带有内部缓冲区的 Read 类型，它可以执行其他读取方式。
Read	Read trait 允许从源读取字节。
Seek	Seek trait 提供了一个游标，可以在字节流中移动它。
Write	trait 用于面向字节的 sinks 的对象。

Functions

read_to_string	Experimental 将 reader 的所有字节读入新的 String。
stderr_locked	Experimental 为当前进程的标准错误创建一个新的锁定句柄。
stdin_locked	Experimental 为当前进程的标准输入创建一个新的锁定句柄。
stdout_locked	Experimental 为当前进程的标准输出创建一个新的锁定句柄。
copy	将 reader 的全部内容复制到 writer 中。
empty	为空的 reader 创建一个新的句柄。
repeat	创建 reader 的实例，该实例无限重复一个字节。
sink	创建 writer 的实例，该实例将成功使用所有数据。
stderr	为当前进程的标准错误创建一个新的句柄。
stdin	为当前进程的标准输入创建一个新的句柄。
stdout	为当前进程的标准输出创建一个新的句柄。

Type Definitions

Result

I/O 操作的专用 Result 类型。