Std::getline

From aldeid
Jump to: navigation, search

Syntax

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

Description

Get line from stream into string

Extracts characters from is and stores them into str until the delimitation character delim is found (or the newline character, '\n', for (2)).

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).

Note that any content in str before the call is replaced by the newly extracted sequence.

Each extracted character is appended to the string as if its member push_back was called.

Parameters

is
istream object from which characters are extracted.
str
string object where the extracted line is stored.
The contents in the string before the call (if any) are discarded and replaced by the extracted line.

Return Value

The same as parameter is.

A call to this function may set any of the internal state flags of is if:

flag error
eofbit The end of the source of characters is reached during its operations.
failbit The input obtained could not be interpreted as a valid textual representation of an object of this type.

In this case, distr preserves the parameters and internal data it had before the call.

Notice that some eofbit cases will also set failbit.

badbit An error other than the above happened.

(see ios_base::iostate for more info on these)

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

In the below example, we're asking for a name (that may contain spaces). Hence we should use getline instead of std::cin because if we don't, the program won't go through the remaining questions. The reason is that the space will be considered as the end of the name though the buffer will still contain the string after the space.

Source Run
#include <iostream>
#include <string>

using namespace std;

int main()
{
  int age(0), nkids(0);
  string name("");

  cout << "What's your name? ";
  getline(cin, name);

  cout << "How old are you? ";
  cin >> age;

  cout << "How may kids do you have? ";
  cin >> nkids;

  cout << "Hello " << name << ". You are " << age << " years old and have " << nkids << " kids." << endl;
  return 0;
}
$ ./main
What's your name? Alice Shaw
How old are you? 38
How may kids do you have? 3
Hello Alice Shaw. You are 38 years old and have 3 kids.

Now, if cin is called before getline, you should insert cin.ignore(); before calling getline.

Source Run
#include <iostream>
#include <string>

using namespace std;

int main()
{
  int age(0);
  string name("");

  cout << "How old are you? ";
  cin >> age;

  cout << "What's your name? ";
  getline(cin, name);

  cout << "Hello " << name << ". You are " << age << " years old." << endl;
  return 0;
}
$ ./main 
How old are you? 37
What's your name? Hello . You are 37 years old.
#include <iostream>
#include <string>

using namespace std;

int main()
{
  int age(0);
  string name("");

  cout << "How old are you? ";
  cin >> age;

  // Ignore ENTER of previous question
  cin.ignore();
  
  cout << "What's your name? ";
  getline(cin, name);

  cout << "Hello " << name << ". You are " << age << " years old." << endl;
  return 0;
}
$ ./main 
How old are you? 37
What's your name? Alice Shaw
Hello Alice Shaw. You are 37 years old.