std::basic_stringbuf<CharT,Traits,Allocator>::overflow
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 returns 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.
Contents |
[edit]Parameters
| c | - | the character to store in the put area |
[edit]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.
[edit]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::basic_stringbuf, the buffer and the associated sequence are one and the same.
[edit]Example
In the implementation used to execute this example (e.g. GCC-4.9), overflow() over-allocates the put area to 512 bytes: a call to str() would only return the four initialized bytes, but the next 508 calls to sputc() would not require new calls to overflow().
#include <sstream>#include <iostream> struct mybuf :std::stringbuf{ mybuf(conststd::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 streamstd::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 streamstd::iostream ro_stream(&ro_buf); ro_stream <<1234; std::cout<<"\nwrite-only stream:\n"; mybuf wr_buf(" ", std::ios_base::out);// write-only streamstd::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[edit]Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 169 | C++98 | the buffer (re)allocated could only hold one extra character | allows more extra characters |
| LWG 432 | C++98 | overflow moved epptr() to point just past the newwrite position if the std::stringbuf is open for input | it is not moved |
[edit]See also
[virtual] | writes characters to the associated output sequence from the put area (virtual protected member function of std::basic_streambuf<CharT,Traits>) |
[virtual] | returns the next character available in the input sequence (virtual protected member function) |
