C++

參考

<istream>

basic_istream

public member function
<istream> <iostream>

std::basic_istream::get

單個字元 (1)
int_type get();basic_istream& get (char_type& c);
c-string (2)
basic_istream& get (char_type* s, streamsize n);basic_istream& get (char_type* s, streamsize n, char_type delim);
stream buffer (3)
basic_istream& get (basic_streambuf<char_type,traits_type>& sb);basic_istream& get (basic_streambuf<char_type,traits_type>& sb, char_type delim);
Get characters
Extracts characters from the stream, as unformatted input

(1) single character
Extracts a single character from the stream.
The character is either returned (first signature), or set as the value of its argument (second signature).
(2) c-string
Extracts characters from the stream and stores them in s as a c-string, until either (n-1) characters have been extracted or the delimiting character is encountered: the delimiting character being either the newline character (widen('\n')) or delim (if this argument is specified).
The delimiting character is not extracted from the input sequence if found, and remains there as the next character to be extracted from the stream (see getline for an alternative that does discard the delimiting character).
A null character (char_type()) is automatically appended to the written sequence if n is greater than zero, even if an empty string is extracted.
(3) stream buffer
Extracts characters from the stream and inserts them into the output sequence controlled by the stream buffer object sb, stopping either as soon as such an insertion fails or as soon as the delimiting character is encountered in the input sequence (the delimiting character being either the newline character or delim, if this argument is specified).
Only the characters successfully inserted into sb are extracted from the stream: Neither the delimiting character, nor eventually the character that failed to be inserted at sb, are extracted from the input sequence and remain there as the next character to be extracted from the stream.

The function also stops extracting characters if the end-of-file is reached. If this is reached prematurely (before meeting the conditions described above), the function sets the eofbit flag.

Internally, the function accesses the input sequence by first constructing a sentry object (with noskipws set to true). Then (if good), it extracts characters from its associated stream buffer object as if calling its member functions sbumpc or sgetc, and finally destroys the sentry object before returning.

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

引數

c
The reference to a character where the extracted value is stored.
s
指向字元陣列的指標，提取的字元將作為 c 字串儲存在其中。
If the function does not extract any characters (or if the first character extracted is the delimiter character) and n is greater than zero, this is set to an empty c-string.
n
Maximum number of characters to write to s (including the terminating null character).
If this is less than 2, the function does not extract any characters and sets failbit.
streamsize 是一個帶符號整型。
delim
Explicit delimiting character: The operation of extracting successive characters stops as soon as the next character to extract compares equal to this (using traits_type::eq).
sb
A basic_streambuf object on whose controlled output sequence the characters are copied.
成員型別 char_type 是流使用的字元型別（即其第一個類模板引數 charT）。

返回值

The first signature returns the character read, or the end-of-file value (traits_type::eof()) if no characters are available in the stream (note that in this case, the failbit flag is also set).

成員型別int_type是能夠表示任何字元值或特殊*檔案結束*符的整型。

All other signatures always return *this. Note that this return value can be checked for the state of the stream (see casting a stream to bool for more info).

Errors are signaled by modifying the internal state flags
flagerror
eofbit函式停止提取字元，因為輸入序列沒有更多可用字元（已到達 檔案末尾）。
failbitEither no characters were written or an empty c-string was stored in s.
badbit流錯誤（例如，當此函式捕獲由內部操作丟擲的異常時）。
When set, the integrity of the stream may have been affected.
Multiple flags may be set by a single operation.

If the operation sets an internal state flag that was registered with member exceptions, the function throws an exception of member type failure.

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 
// istream::get example
#include <iostream>     // std::cin, std::cout
#include <fstream>      // std::ifstream

int main () {
  char str[256];

  std::cout << "Enter the name of an existing text file: ";
  std::cin.get (str,256);    // get c-string

  std::ifstream is(str);     // open file

  char c;
  while (is.get(c))          // loop getting single characters
    std::cout << c;

  is.close();                // close file

  return 0;
}

This example prompts for the name of an existing text file and prints its content on the screen, using cin.get both to get individual characters and c-strings.

資料競爭

Modifies c, sb or the elements in the array pointed by s.
修改流物件。
Concurrent access to the same stream object may cause data races, except for the standard stream objects cin and wcin when these are synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which extracted characters are attributed to threads).

異常安全

基本保證：如果丟擲異常，物件處於有效狀態。
It throws an exception of member type failure if the resulting error state flag is not goodbit and member exceptions was set to throw for that state.
Any exception thrown by an internal operation is caught and handled by the function, setting badbit. If badbit was set on the last call to exceptions, the function rethrows the caught exception.

另見

basic_istream::getline
獲取行 (公共成員函式)
basic_istream::ignore
提取並丟棄字元 (公共成員函式)
basic_istream::gcount
獲取字元計數 (公共成員函式)