public member function
<istream> <iostream>

std::istream::read

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

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

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

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

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

参数

s
指向存储提取字符的数组的指针。
n
要提取的字符数。
streamsize 是一个带符号整型。

返回值

istream 对象 (*this)。

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

如果操作设置了通过成员 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 指向的数组中的元素以及流对象。
同时访问同一流对象可能会导致数据竞争,标准流对象 cin与 stdio 同步时除外(在这种情况下,不会引发数据竞争,尽管不保证提取的字符归属于线程的顺序)。

异常安全

基本保证:如果抛出异常,对象处于有效状态。
如果操作设置的错误状态标志不是 goodbit 并且 exceptions 成员被设置为对该状态进行抛出,则会抛出类型为 failure 的异常。
内部操作抛出的任何异常都会被捕获并由该函数处理,从而设置 badbit。如果在上次调用 exceptions 时设置了 badbit,则该函数将重新抛出捕获到的异常。

另见