public member function

std::istream::getline

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

Get line

Extracts characters from the stream as unformatted input and stores them into s as a c-string, until either the extracted character is the delimiting character, or n characters have been written to s (including the terminating null character).

The delimiting character is the newline character ('\n') for the first form, and delim for the second: when found in the input sequence, it is extracted from the input sequence, but discarded and not written to s.

The function will also stop extracting characters if the end-of-file is reached. If this is reached prematurely (before either writing n characters or finding delim), the function sets the eofbit flag.

The failbit flag is set if the function extracts no characters, or if the delimiting character is not found once (n-1) characters have already been written to s. Note that if the character that follows those (n-1) characters in the input sequence is precisely the delimiting character, it is also extracted and the failbit flag is not set (the extracted sequence was exactly n characters long).

A null character ('\0') is automatically appended to the written sequence if n is greater than zero, even if an empty string is extracted.

Internally, the function accesses the input sequence by first constructing a sentry object (with noskipws set to true). Then (if good), it extracts characters from its associated stream buffer object as if calling its member functions sbumpc or sgetc, and finally destroys the sentry object before returning.

The number of characters successfully read and stored by this function can be accessed by calling member gcount.

This function is overloaded for string objects in header <string>: See getline(string).

Parameters

s: Pointer to an array of characters where extracted characters are stored as a c-string.
n: Maximum number of characters to write to s (including the terminating null character).
If the function stops reading because this limit is reached without finding the delimiting character, the failbit internal flag is set.
streamsize is a signed integral type.
delim: Explicit delimiting character: The operation of extracting successive characters stops as soon as the next character to extract compares equal to this.

Return Value

The istream object (*this).

Errors are signaled by modifying the internal state flags:

flag	error
`eofbit`	The function stopped extracting characters because the input sequence has no more characters available (end-of-file reached).
`failbit`	Either the delimiting character was not found or no characters were extracted at all (because the end-of-file was before the first character or because the construction of `sentry` failed).
`badbit`	Error on stream (such as when this function catches an exception thrown by an internal operation). When set, the integrity of the stream may have been affected.

Multiple flags may be set by a single operation.

If the operation sets an internal state flag that was registered with member exceptions, the function throws an exception of member type failure.

Example

// istream::getline example
#include <iostream>     // std::cin, std::cout

int main () {
  char name[256], title[256];

  std::cout << "Please, enter your name: ";
  std::cin.getline (name,256);

  std::cout << "Please, enter your favourite movie: ";
  std::cin.getline (title,256);

  std::cout << name << "'s favourite movie is " << title;

  return 0;
}

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

Data races

Modifies the elements in the array pointed by s and the stream object.
Concurrent access to the same stream object may cause data races, except for the standard stream object cin when this is synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which extracted characters are attributed to threads).

Exception safety

Basic guarantee: if an exception is thrown, the object is in a valid state.
It throws an exception of member type failure if the resulting error state flag is not goodbit and member exceptions was set to throw for that state.
Any exception thrown by an internal operation is caught and handled by the function, setting badbit. If badbit was set on the last call to exceptions, the function rethrows the caught exception.

class templates

classes

manipulators

member classes

member functions

non-member overloads

protected members