cpp/io/strstreambuf/pbackfail

This protected virtual function is called by the public functions and  (which, in turn, are called by  and ).

@1@ The caller is requesting that the get area is backed up by one character ( is called with no arguments or with eof as the argument)
 * @a@ First, checks if there is a putback position, and if there really isn't, fails. (strstreambuf has no external character source to re-read)
 * @b@ If the caller was wrong and the putback position is in fact available, simply decrements, e.g. by calling.

@2@ The caller attempts to putback a different character from the one retrieved earlier ( is called with the character that needs to be put back), in which case
 * @a@ First, checks if there is a putback position, and if there isn't, fails.
 * @b@ Then checks what character is in the putback position. If the character held there is already equal to, then simply decrements.
 * @c@ Otherwise, if the buffer is unmodifiable (this strstreambuf was constructed with a string literal or some other array), fails.
 * @d@ Otherwise, decrements and writes  to the location pointed to gptr after adjustment.

Return value
on success except if was eof, in which case unspecified value other than eof is returned.

eof on failure.