diff options
| -rw-r--r-- | common/stream.h | 24 |
1 files changed, 24 insertions, 0 deletions
diff --git a/common/stream.h b/common/stream.h index 1e9e02593b..26c04e5bf6 100644 --- a/common/stream.h +++ b/common/stream.h @@ -42,12 +42,18 @@ public: * Returns true if an I/O failure occurred. * This flag is never cleared automatically. In order to clear it, * client code has to call clearErr() explicitly. + * + * @note The semantics of any implementation of this method are + * supposed to match those of ISO C ferror(). */ virtual bool err() const { return false; } /** * Reset the I/O error status as returned by err(). * For a ReadStream, also reset the end-of-stream status returned by eos(). + * + * @note The semantics of any implementation of this method are + * supposed to match those of ISO C clearerr(). */ virtual void clearErr() {} }; @@ -61,6 +67,9 @@ public: * Write data into the stream. Subclasses must implement this * method; all other write methods are implemented using it. * + * @note The semantics of any implementation of this method are + * supposed to match those of ISO C fwrite(). + * * @param dataPtr pointer to the data to be written * @param dataSize number of bytes to be written * @return the number of bytes which were actually written. @@ -72,6 +81,9 @@ public: * storage medium; unbuffered streams can use the default * implementation. * + * @note The semantics of any implementation of this method are + * supposed to match those of ISO C fflush(). + * * @return true on success, false in case of a failure */ virtual bool flush() { return true; } @@ -155,6 +167,11 @@ public: * Returns true if a read failed because the stream end has been reached. * This flag is cleared by clearErr(). * For a SeekableReadStream, it is also cleared by a successful seek. + * + * @note The semantics of any implementation of this method are + * supposed to match those of ISO C feof(). In particular, in a stream + * with N bytes, reading exactly N bytes from the start should *not* + * set eos; only reading *beyond* the available data should set it. */ virtual bool eos() const = 0; @@ -162,6 +179,10 @@ public: * Read data from the stream. Subclasses must implement this * method; all other read methods are implemented using it. * + * @note The semantics of any implementation of this method are + * supposed to match those of ISO C fread(), in particular where + * it concerns setting error and end of file/stream flags. + * * @param dataPtr pointer to a buffer into which the data is read * @param dataSize number of bytes to be read * @return the number of bytes which were actually read. @@ -335,6 +356,9 @@ public: * position indicator, or end-of-file, respectively. A successful call * to the seek() method clears the end-of-file indicator for the stream. * + * @note The semantics of any implementation of this method are + * supposed to match those of ISO C fseek(). + * * @param offset the relative offset in bytes * @param whence the seek reference: SEEK_SET, SEEK_CUR, or SEEK_END * @return true on success, false in case of a failure |