# std::getline

From cppreference.com
< cpp‎ | string‎ | basic string

Defined in header `<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 ); | (2) | (since 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 ); | (3) |
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 ); | (4) | (since C++11)

`getline` reads characters from an input stream and places them into a string:

1-2) Behaves as UnformattedInputFunction, except that input.gcount() is not affected. After constructing and checking the sentry object, performs the following:
1) Calls str.erase()
2) Extracts characters from input and appends them to str until one of the following occurs (checked in the order listed)
a) end-of-file condition on input, in which case, `getline` sets `eofbit`.
b) the next available input character is delim, as tested by Traits::eq(c, delim), in which case the delimiter character is extracted from input, but is not appended to str.
c) str.max_size() characters have been stored, in which case `getline` sets `failbit` and returns.
3) If no characters were extracted for whatever reason (not even the discarded delimiter), `getline` sets `failbit` and returns.
3-4) Same as getline(input, str, input.widen('\n')), that is, the default delimiter is the endline character.

### Parameters

input | - | the stream to get data from
str | - | the string to put the data into
delim | - | the delimiter character

### Return value

input

### Notes

When consuming whitespace-delimited input (e.g. int n; std::cin >> n;) any whitespace that follows, including a newline character, will be left on the input stream. Then when switching to line-oriented input, the first line retrieved with `getline` will be just that whitespace. In the likely case that this is unwanted behaviour, possible solutions include:

- An explicit extraneous initial call to `getline`
- Removing consecutive whitespace with std::cin >> std::ws
- Ignoring all leftover characters on the line of input with cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');

### Example

The following example demonstrates how to use the `getline` function to read user input, and to process a stream line by line, or by parts of a line using the `delim` parameter.

Run this code

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

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

        // read file line by line
        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\n";

        // use separator to read parts of the line
        std::istringstream input2;
        input2.str("a;b;c;d");
        for (std::string line; std::getline(input2, line, ';'); )
            std::cout << line << '\n';
    }

Possible output:

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

    The sum is 28.

    a
    b
    c
    d

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR | Applied to | Behavior as published | Correct behavior
--- | --- | --- | ---
LWG 91 | C++98 | `getline` did not behave as an unformatted input function | behaves as an unformatted input function

### See also

getline | extracts characters until the given character is found (public member function of `std::basic_istream<CharT,Traits>`)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/getline&oldid=152682"