cin.getline用法说明 - from C++ reference



std::istream::getline

istream& getline (char* s, streamsize n );istream& getline (char* s, streamsize n, char delim );

Get line

Extracts characters from the stream as unformatted input and stores them intos as a c-string, until either the extracted character is the delimiting character, orn characters have been written to s (including the terminating null character).

此函数从流类对象中抽取字符作为非格式化的输入以c-string类型存储到 s 中，直到抽取到 delimiting character（作为界限的字符 '\n'）或者写入到s中的字符的数量（包括作为字符串结尾的'\0'字符）已经达到n 为止。

 The delimiting character is the newline character ('\n') for the first form, anddelim for the second: when found in the input sequence, it is extracted from the input sequence, but discarded and not written tos.

所谓的delimiting character在默认情况下就是newline character（'\n'），在函数带参（delim）的情况下以delim作为delimiting character, 具体情况是，当delimiting character出现在输入字符串中时，它会被从输入序列中提取出来，但是会被舍弃，不会被写入到s中。

 The function will also stop extracting characters if the end-of-file is reached. If this is reached prematurely (before either writingn characters or finding delim), the function sets the eofbit flag.

如果文件或者输入的字符串达到了文件结束符（end-of-file），该函数也会停止。如果这种情况过早出现（在写入s的字符数量达到n或者找到delim之前），该函数会在内置标志字中设置eofbit的标志。

 The failbit flag is set if the function extracts no characters, or if thedelimiting character is not found once (n-1) characters have already been written tos. Note that if the character that follows those (n-1) characters in the input sequence is precisely thedelimiting character, it is also extracted and the failbit flag is not set (the extracted sequence was exactlyn characters long).

如果函数没有提取到任何字符或者delimiting character在s中已经写入（n - 1）个字符的时候仍然没有出现，那么函数将会在内置标志字中设置failbit标志。需要注意的是，如果输入序列中的第n 个字符恰好是delimiting character，那么它仍然会被提取但是failbit的标志不会被设置（被输入的字符串的长度恰好是n）。

 A null character ('\0') is automatically appended to the written sequence ifn is greater than zero, even if an empty string is extracted.

系统会在写入的字符串的末尾追加字符null character（'\0'）只要n>0，即便是空字符串（没有提取到任何字符）。

 Internally, the function accesses the input sequence by first constructing a sentry object (withnoskipws set to true). Then (if good), it extracts characters from its associatedstream buffer object as if calling its member functionssbumpc orsgetc, and finally destroys thesentry object before returning.

函数在处理输入字符串（input sequence）时会首先创建一个sentry对象（并把 noskipws 设置为 true）。然后（如果创建成功），它会从与它相关联的stream buffer 对象中抽取字符，就像调用它的成员函数sbumpc 或者 sgetc，然后最终在函数返回之前把该 sentry 对象注销。

 The number of characters successfully read and stored by this function can be accessed by calling membergcount.

本函数成功读取和存储的字符数量可以通过调用 gcount 获得。

 This function is overloaded for string objects in header<string>: Seegetline(string).

本函数在<string>库中有以 string 对象为参数的函数重载。参见 getline(string)。

Parameters （函数参数）

s

Pointer to an array of characters where extracted characters are stored as a c-string.

用来存储 c-string 对象的（字符串）的数组的指针（即数组名）

n

Maximum number of characters to write to s (including the terminating null character).

能够写入s的最大字符数（包括串尾符 '\0'）
 If the function stops reading because this limit is reached without finding the delimiting character, the failbit internal flag is set.
streamsize is a signed integral type.

如果函数因为已经读入了n个字符却仍未发现结束标记（delimiting character），那么函数将在内置标志字中设置failbit标志。

delim

Explicit delimiting character: The operation of extracting successive characters stops as soon as the next character to extract compares equal to this.

delim即delimiting character，一旦下一个字符与delim相同，函数就停止读取字符。

Return Value （返回值）

The istream object (*this).

Errors are signaled by modifying the internal state flags:

错误通过修改内置标志字来标明。

flagerroreofbit

The function stopped extracting characters because the input sequence has no more characters available (end-of-file reached).

函数因为无法再提取更多的字符而停止（达到文件结束标志 end-of-file）

failbit

Either the delimiting character was not found or no characters were extracted at all (because theend-of-file was before the first character or because the construction ofsentry failed).

没有发现结束符（delimiting character），或者没有提取到任何字符（因为文件结束符end-of-file出现在需要读入的字符串之前或者sentry的创建失败）。

badbit

Error on stream (such as when this function catches an exception thrown by an internal operation).
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 memberexceptions, the function throws an exception of member typefailure.

如果函数设置了一个用成员异常注册的内部标志字，该函数会抛出一个member type failure的异常。