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 設定為丟擲,則函式會重新丟擲捕獲到的異常。

另見