C++

參考

<istream>

basic_istream

public member function
<istream> <iostream>

std::basic_istream::getline

basic_istream& getline (char_type* s, streamsize n );basic_istream& getline (char_type* s, streamsize n, char_type delim);
獲取行
從流中提取字元作為非格式化輸入，並將它們儲存在 s 中，作為 C 字串，直到提取的字元是分隔符，或者 n 個字元已寫入 s（包括終止的空字元）。

分隔符是換行符（widen('\n')），對於第二種形式，則是 delim：當在輸入序列中找到它時，它將從輸入序列中提取，但會被丟棄，不會寫入 s。

提取字元的函式也會在到達檔案結尾時停止。如果在此之前（在寫入 n 個字元或找到 delim 之前）到達檔案結尾，該函式會將 eofbit 標誌設定為 true。

如果函式未提取任何字元，或者由於檔案結尾在第一個字元之前，或者 sentry 的構造失敗而未找到分隔符，則 failbit 標誌將被設定為 true。請注意，如果輸入序列中緊跟這 (n-1) 個字元的字元恰好是分隔符，它也會被提取，並且 failbit 標誌不會被設定（提取的序列恰好是 n 個字元長）。

即使提取的是空字串，如果 n 大於零，也會自動在寫入的序列末尾新增一個空字元（char_type()）。

在內部，該函式透過首先構造一個 sentry 物件（將 noskipws 設定為 true）來訪問輸入序列。然後（如果good），它會像呼叫其成員函式 sbumpc 或 sgetc 一樣，從其關聯的流緩衝區物件中提取字元，最後在返回前銷燬 sentry 物件。

透過呼叫成員函式 gcount 可以訪問此函式成功讀取並存儲的字元數。

此函式已為 basic_string 物件在標頭檔案 <string> 中過載：請參閱 getline(basic_string)。

引數

s
指向字元陣列的指標，提取的字元將作為 c 字串儲存在其中。
n
要寫入 s 的字元的最大數量（包括終止的空字元）。
如果函式因達到此限制而停止讀取，而未找到分隔符，則會將 failbit 內部標誌設定為 true。
streamsize 是一個帶符號整型。
delim
顯式分隔符：提取連續字元的操作會立即停止，只要下一個要提取的字元與此字元相等（使用 traits_type::eq）。
成員型別 char_type 是流使用的字元型別（即其第一個類模板引數 charT）。

返回值

*this 的 basic_istream 物件。

錯誤透過修改內部狀態標誌來指示。
flagerror
eofbit函式停止提取字元，因為輸入序列沒有更多可用字元（已到達 檔案末尾）。
failbit未找到分隔符，或者根本沒有提取字元（因為檔案結尾在第一個字元之前，或者 sentry 的構造失敗）。
badbit流錯誤（例如，當此函式捕獲由內部操作丟擲的異常時）。
設定為 true 時，流的完整性可能受到影響。
一次操作可能設定多個標誌。

如果操作設定了一個已透過成員 exceptions 註冊的內部狀態標誌，則函式將丟擲成員型別為 failure 的異常。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
// istream::getline example
#include <iostream>     // std::cin, std::cout

int main () {
  char name[256], title[256];

  std::cout << "Please, enter your name: ";
  std::cin.getline (name,256);

  std::cout << "Please, enter your favourite movie: ";
  std::cin.getline (title,256);

  std::cout << name << "'s favourite movie is " << title;

  return 0;
}

此示例說明了如何從標準輸入流（cin）獲取行。

資料競爭

修改 s 指向的陣列中的元素以及流物件。
同時訪問同一個流物件可能導致資料競爭，標準流物件 cin 和 wcin 在與 stdio同步時除外（在這種情況下，不會引發資料競爭，儘管對提取字元歸屬給執行緒的順序沒有保證）。

異常安全

基本保證：如果丟擲異常，物件處於有效狀態。
如果生成的錯誤狀態標誌不是 goodbit 並且 exceptions 成員被設定為針對該狀態丟擲，則丟擲型別為 failure 的異常。
內部操作丟擲的任何異常都會被函式捕獲並處理，從而設定 badbit。如果在最後一次呼叫 exceptions 時設定了 badbit，則函式會重新丟擲捕獲的異常。

另見

basic_istream::get
獲取字元 (公共成員函式)
basic_istream::ignore
提取並丟棄字元 (公共成員函式)
basic_istream::gcount
獲取字元計數 (公共成員函式)
getline (basic_string)
從流獲取行到字串 (函式模板)