# std::getline

< cpp‎ | string‎ | basic string

定义于头文件 `<string>` |  |
template< class CharT, class Traits, class Allocator > std::basic_istream<CharT,Traits>& getline( std::basic_istream<CharT,Traits>& input, std::basic_string<CharT,Traits,Allocator>& str, CharT delim ); | (1) |
template< class CharT, class Traits, class Allocator > std::basic_istream<CharT,Traits>& getline( std::basic_istream<CharT,Traits>&& input, std::basic_string<CharT,Traits,Allocator>& str, CharT delim ); | (1) | (C++11 起)
template< class CharT, class Traits, class Allocator > std::basic_istream<CharT,Traits>& getline( std::basic_istream<CharT,Traits>& input, std::basic_string<CharT,Traits,Allocator>& str ); | (2) |
template< class CharT, class Traits, class Allocator > std::basic_istream<CharT,Traits>& getline( std::basic_istream<CharT,Traits>&& input, std::basic_string<CharT,Traits,Allocator>& str ); | (2) | (C++11 起)

`getline` 从输入流读取字符并将它们放进 string ：

1) 表现为无格式输入函数 (UnformattedInputFunction) ，除了不影响 `input.gcount()` 。构造并检查 sentry 对象后，进行下列操作：
1) 调用 str.erase()
2) 从 `input` 释出字符并后附它们到 `str` ，直至发生下列条件之一（按顺序检查）：
a) `input` 上的文件尾条件，该情况下， `getline` 设置 `eofbit` 。
b) 下个可用输入字符是 `delim` ，以 Traits::eq(c, delim) 测试，该情况下从 `input` 释出分隔字符，但不后附它到 `str` 。
c) 已经存储 str.max_size() 个字符，该情况下 `getline` 设置 `failbit` 并返回。
3) 若因任何原因（不是舍弃的分隔符）没有释出字符，则 `getline` 设置 `failbit` 并返回。
2) 同 getline(input, str, input.widen('\n')) ，即默认分隔符是换行符。

### 参数

input | - | 获取数据来源的流
str | - | 放置数据的目标 string
delim | - | 分隔字符

### 返回值

`input`

### 注解

消耗空白符分隔的输入（例如 int n; std::cin >> n; ）时，任何后随的空白符，包括换行符都会被留在流中。然后当切换到面向行的输入时，以 `getline` 取得的首行只会是该空白符。多数情况下这是不想要的行为，可能的解法包括：

- 对 `getline` 的显式的额外初始调用
- 以 std::cin >> std::ws 移除额外的空白符
- 以 std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n'); 忽略输入行上剩下的全部字符

### 示例

下列代码演示如何用 `getline` 函数读取用户输入以及如何逐行处理文件。

    #include <string>
    #include <iostream>
    #include <sstream>

    int main()
    {
        // 问候用户
        std::string name;
        std::cout << "What is your name? ";
        std::getline(std::cin, name);
        std::cout << "Hello " << name << ", nice to meet you.\n";

        // 逐行读文件
        std::istringstream input;
        input.str("1\n2\n3\n4\n5\n6\n7\n");
        int sum = 0;
        for (std::string line; std::getline(input, line); ) {
            sum += std::stoi(line);
        }
        std::cout << "\nThe sum is: " << sum << "\n";
    }

可能的输出：

    What is your name? John Q. Public
    Hello John Q. Public, nice to meet you.

    The sum is 28

### 参阅

getline | 一直读并取走字符，直至找到给定字符 (`std::basic_istream<CharT,Traits>` 的公开成员函数)