cpp/io/basic stringbuf/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 as the argument)
 * @a@ First, checks if there is a putback position, and if there really isn't, fails. (stringbuf 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, as determined by , then simply decrements.
 * @c@ Otherwise, if the buffer is open for reading only, fails.
 * @d@ Otherwise, if the buffer is open for writing ( is nonzero), then decrements and writes  to the location pointed to gptr after adjustment.

Return value
on success except if was, in which case  is returned.

on failure.