c++11 标准模板（STL）（std::basic_istream）（八）

news2024/11/17 21:56:18

定义于头文件 <istream>

template<

class CharT,
class Traits = std::char_traits<CharT>

> class basic_istream : virtual public std::basic_ios<CharT, Traits>

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

无格式输入

读并取走一块字符

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

basic_istream& read( char_type* s, std::streamsize count );

从流释出字符。

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

释出并存储了 count 个字符

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

参数

s	-	指向要存储字符到的字符数组的指针
count	-	要读取的字符数

返回值

*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

std::streamsize readsome( char_type* s, std::streamsize count );

从输入流释出至多 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 所指向的字符数组的相继位置。

参数

s	-	指向要存储字符到的字符数组的指针
count	-	要读取的最大字符数

返回值

实际释出的字符数。

异常

若出现错误（错误状态标志不是 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

std::streamsize gcount() const;

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

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();
}