istream& getline ( istream& is, string& str, char delim );
istream& getline ( istream& is, string& str );

<string>

Get line from stream

Extracts characters from is and stores them into str until a delimitation character is found.

The delimiter character is delim for the first function version, and '\n' (newline character) for the second. The extraction also stops if the end of file is reached in is or if some other error occurs during the input operation.

If the delimiter is found, it is extracted and discarded, i.e. it is not stored and the next input operation will begin after it.

Notice that unlike the c-string versions of istream::getline, these string versions are implemented as global functions instead of members of the stream class.

Parameters

is

istream object on which the extraction operation is performed.

str

string object where the extracted content is stored.

delim

The delimiting character. The operation of extracting succesive characters is stopped when this character is read.

Return Value

Errors are signaled by modifying the internal state flags:

Additionaly, in any of these cases, if the appropriate flag has been set with is's member function ios::exceptions, an exception of type ios_base::failure is thrown.

Example

// getline with strings
#include <iostream>
#include <string>
using namespace std;

int main () {
  string str;
  cout << "Please enter full name: ";
  getline (cin,str);
  cout << "Thank you, " << str << ".\n";
}

This example ilustrates how to get lines from the standard input stream ( cin ).

Basic template member declarations

template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>&
    getline (basic_istream<charT,traits>& is,
             basic_string<charT,traits,Allocator>& str,
             charT delim );
template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>&
    getline (basic_istream<charT,traits>& is,
             basic_string<charT,traits,Allocator>& str );

See also