[Scummvm-devel] Major "bug" / misfeature in the Stream system

[Willem Jan Palenstijn]

Hi all,

As a follow-up to Max's Stream patch from yesterday, I committed a more
invasive change to Stream:

* eos() now only returns true _after_ trying to read past the end
    of the stream. This is consistent with how stdio's feof() works

As supporting changes around this:

* seek() resets the end-of-stream flag if successful
* read() sets the end-of-stream flag when trying to read more data than
     available
* err() returns true if an I/O error occurred. (Reading past the end of
     the stream is not considered an I/O error)
* clearErr() resets the I/O error flag and the end-of-stream flag

For backward compatibility:

* ioFailed() is now equal to eos() || err()
* clearIoFailed() calls clearErr()

[All above references to eos() only apply to ReadStreams. WriteStreams
don't have the concept of end-of-stream, but do have the err() and
clearErr() functions for I/O errors.]



I have attempted to update the custom Stream/File implementations in the
platform backends (dc, ds, ps2, symbian), but am unfortunately not able
to test these. Porters, please double-check and test the modifications.
I also hope the new eos() semantics may allow you to reduce the amount
of custom code because it now closer matches the behaviour feof().

I have also attempted to update all uses of eos() in the engines, but
am also not able to test all of those, because I do not have all
required games.


To minimize the impact of this patch, I have not yet updated:
* graphics/iff.cpp (PackBitsReadStream)
* engines/parallaction (Parallaction::Archive and usage of PackBitsReadStream)
* engines/gob/dataio.cpp (Gob::DataStream)


What remains to be done:
* a lot of regression testing
* update eos() in PackBitsReadStream,Parallaction::Archive,Gob::DataStream
* replace all uses of ioFailed() with correct usage of err() and/or eos()
* add additional unit tests for the Stream classes

Volunteers are, of course, welcome :-)



If you encounter any problems, or if there are any areas in the Stream
documentation in common/stream.h which are unclear or ambiguous, please
let me know.


-Willem Jan