public member function
<istream> <iostream>

std::basic_istream::read

basic_istream& read (char_type* s, streamsize n);
读取数据块
从流中提取 n 个字符,并将它们存储在 s 指向的数组中。

此函数仅复制数据块,不检查其内容,也不在末尾追加“空字符”。

如果输入序列在成功读取 n 个字符之前就耗尽了字符(即到达文件末尾),则 s 指向的数组将包含到目前为止读取的所有字符,并且流的 eofbitfailbit 标志都会被设置。

内部,该函数通过首先构造一个 sentry 对象(并将 noskipws 设置为 true)来访问输入序列。然后(如果 good),它像调用其成员函数 sbumpcsgetc 一样,从其关联的 流缓冲区 对象中提取字符,最后销毁 sentry 对象,然后返回。

通过调用成员函数 gcount 可以访问此函数成功读取并存储的字符数。

参数

s
指向存储提取字符的数组的指针。
成员类型 char_type 是流使用的字符类型(即其第一个类模板参数 charT)。
n
要提取的字符数。
streamsize 是一个带符号整型。

返回值

*thisbasic_istream 对象。

错误通过修改 内部状态标志 来指示
flag错误
eofbit函数停止提取字符,因为输入序列没有更多可用字符(已到达 文件末尾)。
failbit要么函数未能提取 n 个字符,要么 sentry 的构造失败。
badbit流错误(例如,当此函数捕获由内部操作抛出的异常时)。
当设置为 true 时,流的完整性可能受到影响。
一次操作可能设置多个标志。

如果操作设置了一个通过成员函数 exceptions 注册的 内部状态标志,则函数将抛出类型为 failure 的异常。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// read a file into memory
#include <iostream>     // std::cout
#include <fstream>      // std::ifstream

int main () {

  std::ifstream is ("test.txt", std::ifstream::binary);
  if (is) {
    // get length of file:
    is.seekg (0, is.end);
    int length = is.tellg();
    is.seekg (0, is.beg);

    char * buffer = new char [length];

    std::cout << "Reading " << length << " characters... ";
    // read data as a block:
    is.read (buffer,length);

    if (is)
      std::cout << "all characters read successfully.";
    else
      std::cout << "error: only " << is.gcount() << " could be read";
    is.close();

    // ...buffer contains the entire file...

    delete[] buffer;
  }
  return 0;
}

可能的输出
Reading 640 characters... all characters read successfully.


数据竞争

修改 s 指向的数组中的元素以及流对象。
同时访问同一流对象可能导致数据竞争,标准流对象 cinwcin与 stdio 同步 时除外(在这种情况下,不会发生数据竞争,但提取的字符归属到线程的顺序不提供任何保证)。

异常安全

基本保证:如果抛出异常,对象处于有效状态。
如果最终的 错误状态标志 不是 goodbit 且对 exceptions 的最后一次调用设置为在该状态下抛出,则该函数将抛出类型为 failure 的异常。
内部操作抛出的任何异常都会被函数捕获和处理,并设置 badbit。如果对 exceptions 的最后一次调用将 badbit 设置为抛出,则函数会重新抛出捕获到的异常。

另见