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,則該函式將重新丟擲捕獲到的異常。

另見