std::getline

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 );	(1)	(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 );	(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)	(since C++11)

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

1) 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.

2) 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 used immediately after whitespace-delimited input, e.g. after int n; std::cin >> n;, getline consumes the endline character left on the input stream by operator>>, and returns immediately. A common solution is to ignore all leftover characters on the line of input with cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n'); before switching to line-oriented input.

Example

The following example demonstrates how to use getline function to read user's input and how to process file line by line.

Run this code

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

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";
}

Possible output:

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

The sum is 28

Language
Headers
Freestanding and hosted implementations
Named requirements
Language support library
Concepts library (C++20)
Diagnostics library
Utilities library
Strings library
Containers library
Algorithms library
Iterators library
Numerics library
Input/output library
Localizations library
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)
Filesystem library (C++17)
Technical Specifications

Null-terminated strings
Byte strings
Multibyte strings
Wide strings
Classes
basic_string
basic_string_view (C++17)
char_traits

std::getline

Parameters

Return value

Notes

Example

See also