Reference
C Library
IOstream Library
Strings library
STL Containers
STL Algorithms
Miscellaneous
Strings library
char_traits
classes:
string
global functions:
getline
operator+
operator<<
operator>>
comparison operators
swap


getline

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

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

The same as parameter is.

Errors are signaled by modifying the internal state flags:

flagerror
eofbitThe end of the source of characters is reached during its operations.
failbitNo characters were extracted because the end was prematurely found.Notice that some eofbit cases will also set failbit.
badbitAn error other than the above happened.

Additionally, 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

1
2
3
4
5
6
7
8
9
10
11
 
// 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

( basic_istream<charT,traits> )
1
2
3
4
5
6
7
8
9
 
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

operator>> Extract string from istream (function)
istream::getline Get line from stream (public member function)