overflow

The virtual function overflow() is called to send some characters to the consumer, and establish the put area. Usually (but not always) when it is called, the put area has no space remaining.

   int fctbuf::overflow(int c) {
   	// check that output is allowed
    	if ( !(mode&ios::out) ) return EOF ;
   

   	// Make sure there is a holding area
   	if (  allocate()==EOF ) return EOF ;
   

   	// Verify that there are no characters in
   	// get area.
   	if ( gptr() && gptr() < egptr() ) return EOF ;
   

   	// Reset get area
   	setg(0,0,0) ;
   

   	// Make sure there is a put area
   	if ( !pptr() ) setp(base(),base()) ;
   

   	// Determine how many characters have been
   	// inserted but not consumed.
   	int w = pptr()-pbase() ;
   

   	// If c is not EOF it is a character that must
   	// also be consumed.
   	if ( c != EOF ) {
   		// We always leave space
   		*pptr() = c ;
   		++w ;
   		}
   

   	// consume characters.
   	int ok = (*fct)(pbase(), w, ios::out) ;	
   

   	if ( ok ) {
   		// Set up put area.  Be sure that there
   		// is space at end for one extra character.
   		setp(base(),ebuf()-1) ;
   		return zapeof(c) ;
   		}
   	else {
   		// Indicate error.
   		setp(0,0) ;
   		return EOF ;
   		}
   	}

• It first tests for various error conditions, such as trying to do insertion when there are characters that have been produced but not extracted. This is a problem because the code only uses one area to hold characters for insertion and extraction. It would also be possible to ignore this condition and just throw away the characters or a more elaborate version of fctbuf might use separate areas for insertion and extraction.

• allocate() is a part of the streambuf protected interface. If no reserve area has previously been specified it allocates heap space.

• pbase is the value of pptr established by the last call to setp(). As characters are stored, pptr is moved so that it always points to the first unused character. Thus the characters between pbase and pptr have been stored and not consumed. They are now sent to the consumer.

• The value returned by the consumer is checked to verify that it has been able to consume all the characters that were passed to it. If not, there is no put area and EOF is returned.

• When all has gone well the put area is established by setp() whose first argument becomes pptr (pointing to the first char of the put area) and whose second becomes epptr (pointing to the char after the last char of the put area). In this case when no errors have occurred the whole holding area minus the last character is used as a put area. The last character will usually be filled in by the character supplied to the next call to overflow().

• Finally, if all has gone well, c is returned unless it is EOF. If c is EOF something else must be returned because EOF is returned to signal an error. The macro zapeof() deals with this contingency.