# std::getline

> C++ Atlas: `cppatlas.com/w/cpp/string/basic_string/getline` | Source: https://en.cppreference.com/w/cpp/string/basic_string/getline | Domain: Strings | Standards: C++11

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

## Official Specification Summary (cppreference)

```cpp
// 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.

```cpp
#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:

```text
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`](https://en.cppreference.com/w/cpp/io/basic_istream/getline): extracts characters until the given character is found (public member function of `std::basic_istream<CharT,Traits>`)

---
Attribution: content from https://en.cppreference.com/w/cpp/string/basic_string/getline (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.