定义于头文件 <istream>

 类模板 basic_istream 提供字符流上的高层输入支持。受支持操作包含带格式的输入（例如整数值或空白符分隔的字符与字符串）和无格式输入（例如未处理字符和字符数组）。此功能以通过 basic_ios 基类访问的底层 basic_streambuf 类所提供的接口实现。大多数库实现中， basic_istream 有一个非继承数据成员：用于存储 basic_istream::gcount() 所返回的值。

无格式输入

读并取走一块字符

std::basic_istream<CharT,Traits>::read

从流释出字符。

表现为无格式输入函数 (UnformattedInputFunction) 。构造并检查 sentry 对象后，释出字符并存储它们到首元素为 s 所指向的字符数组的相继位置。释出并存储字符，直至出现任何下列条件：

• 释出并存储了 count 个字符

• 输入序列上的文件尾条件（该情况下调用 setstate(failbit|eofbit) ）。成功释出的字符数能用 gcount() 查询。

参数

返回值

*this

异常

若出现错误（错误状态标志不是 goodbit ）并且设置了 exceptions() 为对该状态抛出则为 failure 。

若内部操作抛出异常，则捕获它并设置 badbit 。若对 badbit 设置了 exceptions() ，则重抛该异常。

注意

使用非转换的本地环境时（默认本地环境为非转换），此函数在 std::basic_ifstream 中的覆写者可以为零复制的大块 I/O 优化（通过覆写 std::streambuf::xsgetn ）。

调用示例

#include <iostream>
#include <fstream>
#include <sstream>
#include <string>
#include <cstdint>

int main()
{
    // read() 常用于二进制 I/O
    std::string bin = {'\x12', '\x12', '\x12', '\x12'};
    std::istringstream raw(bin);
    std::uint32_t n;
    if (raw.read(reinterpret_cast<char*>(&n), sizeof n))
    {
        std::cout << std::hex << std::showbase << n << '\n';
    }

    // 为下个片段准备文件
    std::ofstream("test.txt", std::ios::binary) << "abcd1\nabcd2\nabcd3";

    // 读取整个文件到 string
    if (std::ifstream is{"test.txt", std::ios::binary | std::ios::ate})
    {
        auto size = is.tellg();
        std::string str(size, '\0'); // 构造 string 为流大小
        is.seekg(0);
        if (is.read(&str[0], size))
        {
            std::cout << str << '\n';
        }
    }
}

输出

读并取走已经可用的字符块

std::basic_istream<CharT,Traits>::readsome

从输入流释出至多 count 个立即可用的字符。存储释出的字符于 s 所指向的字符数组。

表现为无格式输入函数 (UnformattedInputFunction) 。构造并检查 sentry 对象后，

• 若 rdbuf()->in_avail() == -1 ，则调用 setstate(eofbit) 而不释出字符。

• 若 rdbuf()->in_avail() == 0 ，则不释出字符。

• 若 rdbuf()->in_avail() > 0 ，则释出 std::min(rdbuf()->in_avail(), count) 个字符，并存储它们到首元素为 s 所指向的字符数组的相继位置。

参数

返回值

实际释出的字符数。

异常

若出现错误（错误状态标志不是 goodbit ）并且设置了 exceptions() 为对该状态抛出则为 failure 。

若内部操作抛出异常，则捕获它并设置 badbit 。若对 badbit 设置了 exceptions() ，则重抛该异常。

注意

此函数的行为是高度实现限定的。例如，以 std::ifstream 使用时，某些库实现在文件打开时立即以数据填充底层 filebuf （而这种实现上 readsome() 读取的数据潜在地，但不必为整个文件），而其他实现仅在请求实际输入操作时从文件读取（而文件打开后立即作出的 readsome() 决不释出任何字符）。类似地，调用 std::cin.readsome() 可能返回所有悬置的未处理控制台输入，或可能始终返回零并且不释出字符。

 调用示例

#include <iostream>
#include <sstream>

int main()
{
    char c[10] = {};
    std::istringstream input("This is sample text."); 
    // std::stringbuf 令个缓冲可用于无阻塞读取
    input.readsome(c, 5); // 读取 'This ' 并存储于 c[0] .. c[4]
    input.readsome(c, 9); // 读取 'is sample' 并存储于 c[0] .. c[8]
    std::cout << c;
}

输出

返回上次无格式输出操作所取走的字符数量

std::basic_istream<CharT,Traits>::gcount

返回最近的无格式输入操作所释出的字符数。

basic_istream 的下列成员函数更改后继的 gcount() 调用的值：

• 移动构造函数
• swap()
• get()
• getline()
• ignore()
• read()
• readsome()
• operator>>(basic_streambuf*)

下列函数设置 gcount() 为零：

• 构造函数
• putback()
• unget()
• peek()

参数

（无）

返回值

最近的无格式输入操作所释出的字符数。

 调用示例

#include <iostream>
#include <sstream>

int main()
{
    char x[20];
    std::istringstream stream("Hello World");

    stream.read(x, sizeof x);
    std::cout << "Characters extracted: " << stream.gcount();
}

输出