Mercurial > archived > louis > epitech > zia-api
changeset 12:3998a5997e02
[Buffer] Added some documentation on the StreamBuffImpl class. It is not finished yet.
author | Zoltan K |
---|---|
date | Sat, 20 Mar 2010 22:02:22 +0100 |
parents | 57b2a2925db8 |
children | 094f9bdd7d3a |
files | src/examples/Buffer/Buffer.hpp |
diffstat | 1 files changed, 99 insertions(+), 6 deletions(-) [+] |
line wrap: on
line diff
--- a/src/examples/Buffer/Buffer.hpp Sat Mar 20 14:45:44 2010 +0100 +++ b/src/examples/Buffer/Buffer.hpp Sat Mar 20 22:02:22 2010 +0100 @@ -4,24 +4,117 @@ #include <streambuf> #include <vector> -class Buffer : public std::streambuf +/** + ** + ** @brief This class is an example of a simple implementation of std::streambuf. + ** It's purpose is only to show how streambuf works. + ** The full documentation is available here: + ** @link a http://cplusplus.com/reference/iostream/streambuf/ @endlink + ** + ** According to the official documentation, we will call @b put, all operations + ** that fill the buffer (such operations are performed by std::ostream) + ** and we will call @b get, all operations that consume the buffer's content + ** (operations performed by std::istream) + ** + ** The std::streambuf abstract class works with two pointers. One @b get pointer + ** and one @b put pointer. These pointers are sets by two methods: + ** setp (set the put pointer) + ** setg (set the get pointer). + ** Anyway, these pointers can be moved using seekoff and seekpos. + ** Any operation that add or remove content from the buffer should move the + ** appropriate pointer. + ** + */ +class StreamBufferImpl : public std::streambuf { public: - Buffer(void); - virtual ~Buffer(void) { } + StreamBufferImpl(void); + virtual ~StreamBufferImpl(void) { } protected: + /** + ** @brief This method sets a new buffer for the put/get operations + ** This method is called by pubsetbuf. + ** @param [in] s A pointer to the array of char where operations will be performed + ** @param [in] n An integer giving the size of the array + ** @return A pointer to the class itself + */ + virtual StreamBufferImpl * setbuf(char *s, std::streamsize n); - virtual int sync(void); - virtual int underflow(void); + /** + ** @brief This method set the @b get and/or @b put pointer to a relative position. + ** @param [in] off offset value. + ** @param [in] way Where the offset takes effect. The possible values are + ** @li @c std::ios_base::beg from the beginning of the stream buffer + ** @li @c std::ios_base::cur from the current position in the stream buffer + ** @li @c std::ios_base::end from the end of the stream buffer + ** @param [in] which Allow us to choose which pointer should be moved. + ** @li @c std::ios_base::in Move the @b get pointer. + ** @li @c std::ios_base::out Move the @b put pointer. + ** @return The new position. Errors (like an invalid position) should be signaled by a value of -1. + */ + virtual std::streampos seekoff(std::streamoff off, + std::ios_base::seekdir way, + std::ios_base::openmode which = std::ios_base::in | std::ios_base::out); + + /** + ** @brief This method set the @b get and/or @b put pointer to an absolute position. + ** @param [in] sp The pointer new position. + ** @param [in] which Allow us to choose which pointer should be moved. + ** @li @c std::ios_base::in Move the @b get pointer. + ** @li @c std::ios_base::out Move the @b put pointer. + ** @return The new position. Errors (like an invalid position) should be signaled by a value of -1. + */ + virtual std::streampos seekpos(std::streampos sp, + std::ios_base::openmode which = std::ios_base::in | std::ios_base::out); + + /** + ** @brief This method is called when there is a need to synchronize + ** the buffer's content with the ``real'' content it represents + ** (a device or anything else). + ** This method is called when std::endl is applied on a stream + ** @return In case of success, zero is returned. + ** Errors are expected to be signaled by any other value, like -1. + */ + virtual int sync(void); + + virtual std::streamsize showmanyc(void); + virtual std::streamsize xsgetn(char * s, streamsize n); + virtual int underflow(void); + virtual int uflow(void); + virtual int pbackfail(int c = EOF); + + /** + ** @brief This method add content to the buffer. + ** @param [in] s An array of char to add to the buffer. + ** @param [in] n The array's length + ** @return The number of characters written to the buffer. + */ + virtual streamsize xsputn(const char * s, streamsize n); + + /** + ** @brief This method is called when there is no more + ** available space on the buffer. This method could be used to allocate a new buffer. + ** @param [in] c the character to be written + ** @return Any value different than EOF in case of success. + ** If the function fails, it should return an EOF or throw an exception + */ + virtual int overflow(int c = EOF); private: - Buffer(const Buffer & cpy); + /** + ** @brief std::streambuf has a private copy constructor + ** we do the same + */ + StreamBufferImpl(const StreamBufferImpl & cpy); private: + /** + ** @brief This is the buffer our class will fill or consume + */ std::vector<char> _rawBuffer; };