Re: [AD] pack_ungetc

[Elias Pschernig <elias@xxxxxxxxxx>]

On Tue, 2007-05-29 at 08:42 +1000, Peter Wang wrote:
> On 2007-05-28, Elias Pschernig <elias@xxxxxxxxxx> wrote:
> > Why is it not in the docs? Attached is a patch to add it.. in case it
> > should be in there.
> 
> It was exposed when we added custom packfiles.  Previously it was
> internal and only used to implement pack_fgets.  The return value should
> be documented:
> 
>        pack_ungetc() returns c on success, or EOF on error.
> 
> Also, we have to do something about pack_fgets, as pack_ungetc only
> guarantees a single pushback, and calling pack_fgets may clobber it.
> Either we document that behaviour, or somehow fix the problem.
> 

I think we should just document it. Also, my first patch was wrong as it
only allowed pushing back the same character just fetched, which would
leave an ambiguity (and remove all justification for the c parameter).
New version attached.

-- 
Elias Pschernig <elias@xxxxxxxxxx>

Index: docs/src/allegro._tx
===================================================================
--- docs/src/allegro._tx	(revision 7888)
+++ docs/src/allegro._tx	(working copy)
@@ -10670,6 +10670,17 @@
    Returns the next character from the stream `f', or EOF if the end of the
    file has been reached.
 
+@@int @pack_ungetc(int c, PACKFILE *f);
+@xref pack_getc
+@shortdesc Moves one single character back to the input buffer.
+   Puts a character back to the file's input buffer. Like with ungetc from
+   libc, only a single push back is guaranteed.
+
+   Note: pack_fgets internally uses pack_ungetc, so never use pack_ungetc
+   directly after using pack_fgetc on a PACKFILE.
+@retval
+   Returns the character pushed back on success, or EOF on error.
+
 @@int @pack_putc(int c, PACKFILE *f);
 @xref pack_fopen, pack_fopen_chunk
 @shortdesc Puts a character in the stream.