home | help 
std::getline(3) 	       C++ Standard Libary		 std::getline(3)

NAME
     std::getline - std::getline

Synopsis
	Defined in header <string>
	template< class CharT, class Traits, class Allocator >

	std::basic_istream<CharT, Traits>&
	    getline( std::basic_istream<CharT, Traits>& input,		   (1)

		     std::basic_string<CharT, Traits, Allocator>& str,
	CharT delim );
	template< class CharT, class Traits, class Allocator >

	std::basic_istream<CharT, Traits>&
	    getline(  std::basic_istream<CharT,  Traits>&& input,	     (2)
     (since C++11)

		     std::basic_string<CharT, Traits, Allocator>& str,
	CharT delim );
	template< class CharT, class Traits, class Allocator >

	std::basic_istream<CharT, Traits>&				   (3)
	    getline( std::basic_istream<CharT, Traits>& input,

		     std::basic_string<CharT, Traits, Allocator>& str );
	template< class CharT, class Traits, class Allocator >

	std::basic_istream<CharT,  Traits>&				     (4)
     (since C++11)
	    getline( std::basic_istream<CharT, Traits>&& input,

		     std::basic_string<CharT, Traits, Allocator>& str );

	getline  reads	characters  from  an input stream and places them into a
     string:

	1,2) Behaves as UnformattedInputFunction, except that input.gcount()  is
     not
	affected.  After  constructing	and checking the sentry object, performs
     the following:
	1) Calls str.erase().
	2) Extracts characters from input and appends them to str until  one  of
     the following
	occurs (checked in the order listed)
	a) end-of-file condition on input, in which case, getline sets eofbit.
	b)   the   next  available  input  character  is  delim,  as  tested  by
     Traits::eq(c, delim),
	in which case the delimiter character is extracted from  input,  but  is
     not appended
	to str.
	c)  str.max_size()  characters	have  been stored, in which case getline
     sets failbit
	and returns.
	3) If no characters were extracted for whatever  reason  (not  even  the
     discarded
	delimiter), getline sets failbit and returns.
	3,4)  Same  as	getline(input, str, input.widen('\n')), that is, the de-
     fault delimiter
	is the endline character.

Parameters
	input - the stream to get data from
	str   - the string to put the data into
	delim - the delimiter character

Return value
	input

Notes
	When consuming whitespace-delimited input (e.g. int n; std::cin  >>  n;)
     any
	whitespace  that follows, including a newline character, will be left on
     the input
	stream. Then when switching to line-oriented input, the first  line  re-
     trieved with
	getline  will  be  just that whitespace. In the likely case that this is
     unwanted
	behaviour, possible solutions include:

	  * An explicit extraneous initial call to getline.
	  * Removing consecutive whitespace with std::cin >> std::ws.
	  * Ignoring all leftover characters on the line of input with
	    cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');.

Example
	The following example demonstrates how to use the  getline  function  to
     read user
	input, and to process a stream line by line, or by parts of a line using
     the delim
	parameter.

     // Run this code

      #include <iostream>
      #include <sstream>
      #include <string>

      int main()
      {
	  // greet the user
	  std::string name;
	  std::cout << "What is your name? ";
	  std::getline(std::cin, name);
	  std::cout << "Hello " << name << ", nice to meet you.\n";

	  // read file line by line
	  std::istringstream input;
	  input.str("1\n2\n3\n4\n5\n6\n7\n");
	  int sum = 0;
	  for (std::string line; std::getline(input, line);)
	      sum += std::stoi(line);
	  std::cout << "\nThe sum is " << sum << ".\n\n";

	  // use separator to read parts of the line
	  std::istringstream input2;
	  input2.str("a;b;c;d");
	  for (std::string line; std::getline(input2, line, ';');)
	      std::cout << line << '\n';
      }

Possible output:
      What is your name? John Q. Public
      Hello John Q. Public, nice to meet you.

      The sum is 28.

      a
      b
      c
      d

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	  DR   Applied to	   Behavior as	published		 Correct
     behavior
	LWG 91 C++98	  getline did not behave as an unformatted behaves as an
     unformatted
			  input  function			     input func-
     tion

See also
	getline extracts characters until the given character is found
		(public member function of std::basic_istream<CharT,Traits>)

http://cppreference.com 	   2024.06.10			 std::getline(3)
home | help