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
获取字符计数 (公共成员函数)