Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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, per-
       forms 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 eof-
       bit.
	  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
       default 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
       retrieved 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		  Cor-
       rect behavior
	  LWG  91  C++98      getline did not behave as	an unformatted behaves
       as an unformatted
			    input   function				 input
       function

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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::getline&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help