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)
从流获取行到字符串 (函数模板)