public member function
<istream> <iostream>

std::basic_istream::getline

basic_istream& getline (char_type* s, streamsize n );
basic_istream& getline (char_type* s, streamsize n, char_type 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 (widen('\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 (char_type()) 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 basic_string objects in header <string>: See getline(basic_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 (using traits_type::eq).
Member type char_type is the type of characters used by the stream (i.e., its first class template parameter, charT).

Return Value

The basic_istream object (*this).

Errors are signaled by modifying the internal state flags:
flagerror
eofbitThe function stopped extracting characters because the input sequence has no more characters available (end-of-file reached).
failbitEither 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).
badbitError 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
// 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 objects cin and wcin when these are 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.

See also

basic_istream::get
Get characters (public member function )
basic_istream::ignore
Extract and discard characters (public member function )
basic_istream::gcount
Get character count (public member function )
getline (basic_string)
Get line from stream into string (function template )

C++

<istream>