home | help 
std::basic_...f::overflow(3)   C++ Standard Libary  std::basic_...f::overflow(3)

NAME
     std::basic_stringbuf::overflow - std::basic_stringbuf::overflow

Synopsis
	protected:
	virtual int_type overflow( int_type c = Traits::eof() );

	Appends the character c to the output character sequence.

	If c is the end-of-file indicator (traits::eq_int_type(c, traits::eof())
     == true),
	then  there is no character to append. The function does nothing and re-
     turns an
	unspecified value other than traits::eof().

	Otherwise, if the output sequence has a write position available or this
     function
	can successfully make a write position available,  then  calls	sputc(c)
     and returns c.

	This  function can make a write position available if the std::stringbuf
     is open for
	output ((mode & ios_base::out) != 0): in this case, it	reallocates  (or
     initially
	allocates)  the buffer big enough to hold the entire current buffer plus
     at least one
	more character. If the std::stringbuf is also open for	input  ((mode  &
     ios_base::in)
	!=  0),  then overflow also increases the size of the get area by moving
     egptr() to
	point just past the new write position.

Parameters
	c - the character to store in the put area

Return value
	Traits::eof() to indicate failure, c if the character c was successfully
     appended,
	or some value other than Traits::eof() if called with  Traits::eof()  as
     the argument.

Notes
	This  function	is  different  from a typical overflow() which moves the
     contents of the
	buffer to the associated  character  sequence  because	for  a	std::ba-
     sic_stringbuf, the
	buffer and the associated sequence are one and the same.

Example
	In the implementation used to execute this example (e.g. GCC-4.9), over-
     flow()
	over-allocates the put area to 512 bytes: a call to str() would only re-
     turn the four
	initialized  bytes,  but the next 508 calls to sputc() would not require
     new calls to
	overflow().

     // Run this code

      #include <sstream>
      #include <iostream>

      struct mybuf : std::stringbuf
      {
	  mybuf(const std::string& new_str,
		std::ios_base::openmode    which    =	 std::ios_base::in     |
     std::ios_base::out)
	      : std::stringbuf(new_str, which) {}

	  int_type overflow(int_type c = EOF) override
	  {
	      std::cout << "stringbuf::overflow('" << char(c) << "') called\n"
			<<  "Before: size of get area: " << egptr() - eback() <<
     '\n'
			<< "	    size of put area: " << epptr() - pbase()  <<
     '\n';

	      int_type ret = std::stringbuf::overflow(c);

	      std::cout  << "After : size of get area: " << egptr() - eback() <<
     '\n'
			<< "	    size of put area: " << epptr() - pbase()  <<
     '\n';

	      return ret;
	  }
      };

      int main()
      {
	  std::cout << "read-write stream:\n";
	  mybuf sbuf("	 "); // read-write stream
	  std::iostream stream(&sbuf);
	  stream << 1234;
	  std::cout << sbuf.str() << '\n';

	  std::cout << "\nread-only stream:\n";
	  mybuf ro_buf("   ", std::ios_base::in); // read-only stream
	  std::iostream ro_stream(&ro_buf);
	  ro_stream << 1234;

	  std::cout << "\nwrite-only stream:\n";
	  mybuf wr_buf("   ", std::ios_base::out); // write-only stream
	  std::iostream wr_stream(&wr_buf);
	  wr_stream << 1234;
      }

Possible output:
      read-write stream:
      stringbuf::overflow('4') called
      Before: size of get area: 3
	      size of put area: 3
      After : size of get area: 4
	      size of put area: 512
      1234

      read-only stream:
      stringbuf::overflow('1') called
      Before: size of get area: 3
	      size of put area: 0
      After : size of get area: 3
	      size of put area: 0

      write-only stream:
      stringbuf::overflow('4') called
      Before: size of get area: 0
	      size of put area: 3
      After : size of get area: 0
	      size of put area: 512

	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  169  C++98      the buffer (re)allocated could only hold one    al-
     lows more extra
			   extra character				   char-
     acters
			   overflow moved epptr() to point just past the
	LWG 432 C++98	   new						   it is
     not moved
			   write position if the std::stringbuf is open
			   for input

See also
	overflow  writes characters to the associated output sequence  from  the
     put area
	[virtual]  (virtual  protected	member	function  of  std::basic_stream-
     buf<CharT,Traits>)

	underflow returns the next character available in the input sequence
	[virtual] (virtual protected member function)

http://cppreference.com 	   2024.06.10	    std::basic_...f::overflow(3)
home | help