std::getline

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Strings library

Null-terminated strings

Byte strings

Multibyte strings

Wide strings

Classes

basic_string

basic_string_view (C++17)

char_traits

 

std::basic_string

Member functions basic_string::basic_string basic_string::~basic_string basic_string::operator= basic_string::assign basic_string::assign_range (C++23) basic_string::get_allocator Element access basic_string::at basic_string::operator[] basic_string::front (DR*) basic_string::back (DR*) basic_string::data basic_string::c_str basic_string::operator  basic_string_view (C++17) Iterators basic_string::beginbasic_string::cbegin (C++11) basic_string::endbasic_string::cend (C++11) basic_string::rbeginbasic_string::crbegin (C++11) basic_string::rendbasic_string::crend (C++11) Capacity basic_string::empty basic_string::sizebasic_string::length basic_string::max_size basic_string::reserve basic_string::capacity basic_string::shrink_to_fit (DR*) Modifiers basic_string::clear basic_string::insert basic_string::insert_range (C++23) basic_string::erase basic_string::push_back basic_string::pop_back (DR*) basic_string::append basic_string::append_range (C++23) basic_string::operator+= basic_string::replace basic_string::replace_with_range (C++23) basic_string::copy basic_string::resize basic_string::resize_and_overwrite (C++23)   basic_string::swap

Search basic_string::find basic_string::rfind basic_string::find_first_of basic_string::find_first_not_of basic_string::find_last_of basic_string::find_last_not_of Operations basic_string::compare basic_string::starts_with (C++20) basic_string::ends_with (C++20) basic_string::contains (C++23) basic_string::substr Constants basic_string::npos Non-member functions operator+ swap(std::basic_string) erase(std::basic_string)erase_if(std::basic_string) (C++20)(C++20) I/O operator<<operator>> getline Comparison operator==operator!=operator<operator>operator<=operator>=operator<=> (until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20) Numeric conversions stoistolstoll (C++11)(C++11)(C++11) stoulstoull (C++11)(C++11) stofstodstold (C++11)(C++11)(C++11) to_string (C++11) to_wstring (C++11) Literals operator""s (C++14) Helper classes hash<std::basic_string> (C++11) Deduction guides (C++17)

 

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