Reference
C Library
IOstream Library
Strings library
STL Containers
STL Algorithms
Miscellaneous

IOstream Library
manipulators
classes:
filebuf
fstream
ifstream
ios
iostream
ios_base
istream
istringstream
ofstream
ostream
ostringstream
streambuf
stringbuf
stringstream
objects:
cerr
cin
clog
cout
types:
fpos
streamoff
streampos
streamsize

istream
istream::istream
istream::~istream
member classes:
istream::sentry
member functions:
istream::gcount
istream::get
istream::getline
istream::ignore
istream::operator>>
istream::peek
istream::putback
istream::read
istream::readsome
istream::seekg
istream::sync
istream::tellg
istream::unget

istream::getline

public member function

istream& getline (char* s, streamsize n );
istream& getline (char* s, streamsize n, char delim );

Get line from stream

Extracts characters from the input sequence and stores them as a c-string into the array beginning at s.

Characters are extracted until either (n - 1) characters have been extracted or the delimiting character is found (which is delim if this parameter is specified, or '\n' otherwise). The extraction also stops if the end of file is reached in the input sequence or if an 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. If you don't want this character to be extracted, you can use member get instead.

The ending null character that signals the end of a c-string is automatically appended to s after the data extracted.

The number of characters read by this function can be obtained by calling to the member function gcount.

A global function with the same name exists in header <string>. This global function provides a similar behavior, but with standard C++ string objects instead of c-strings: see getline (string).

Parameters

s: A pointer to an array of characters where the string is stored as a c-string.
n: Maximum number of characters to store (including the terminating null character).
This is an integer value of type streamsize.
If the function stops reading because this size is reached, the failbit internal flag is set.
delim: The delimiting character. The operation of extracting succesive characters is stopped when this character is read. This parameter is optional, if not specified the function considers '\n' (a newline character) to be the delimiting character.

Return Value

The function returns *this.

Errors are signaled by modifying the internal state flags:

flag	error
`eofbit`	The end of the source of characters is reached during its operations.
`failbit`	No characters were extracted because the end was prematurely found. This is also set if the function stops extracting because n-1 characters were extracted (n including the terminating null-character). Notice that some `eofbit` cases will also set `failbit`.
`badbit`	An error other than the above happened.

Additionally, in any of these cases, if the appropriate flag has been set with 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 12 13 14 15 16 17

// istream getline
#include <iostream>
using namespace std;
int main () {
  char name[256], title[256];
  cout << "Enter your name: ";
  cin.getline (name,256);
  cout << "Enter your favourite movie: ";
  cin.getline (title,256);
  cout << name << "'s favourite movie is " << title;
  return 0;
}

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

Basic template member declarations

( basic_istream<charT,traits> )

1 2 3

typedef charT char_type;
basic_istream& getline (char_type* s, streamsize n );
basic_istream& getline (char_type* s, streamsize n, char_type delim );

istream::getline

Parameters

Return Value

Example

Basic template member declarations

See also