[pclasses-cvs] pclasses2/include/pclasses Buffer.h,1.1,1.2

[Christian P. <cp...@us...>]

Update of /cvsroot/pclasses/pclasses2/include/pclasses
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv12896/include/pclasses

Modified Files:
	Buffer.h 
Log Message:
- Added documentation to P::Buffer 

Index: Buffer.h
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/include/pclasses/Buffer.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- Buffer.h	3 Jun 2005 09:47:42 -0000	1.1
+++ Buffer.h	1 Jul 2005 14:46:02 -0000	1.2
@@ -23,19 +23,34 @@
 
 #include <pclasses/Algorithm.h>
 #include <pclasses/Exception.h>
+#include <pclasses/ScopedArrayPtr.h>
 
 namespace P {
 
+//! Buffer template-class
+/*!
+	A template class used to buffer items of a given type.
+	The class implements FIFO semantics.
+*/
 template <class Type>
 class Buffer {
 	public:
+
+		//! Default constructor
+		/*!
+			Constructs the buffer with the given size and auto-resize policy.
+			\param size the initial size of the buffer
+			\param autoResize true if the buffer should grow as required, false
+				otherwise.
+		*/
 		Buffer(size_t size = 1024, bool autoResize = true)
 		: _autoResize(autoResize),
 		  _buffer((Type*)new char[sizeof(Type) * size]),
-		  _size(size), _count(0)
+		  _size(max((size_t)1, size)), _count(0)
 		{
 		}
 
+		//! Copy constructor
 		Buffer(const Buffer& b)
 		: _autoResize(b._autoResize),
 		  _buffer((Type*)new char[sizeof(Type) * b._size]),
@@ -44,6 +59,7 @@
 			copy_construct(_buffer, b._buffer, _count);
 		}
 
+		//! Destructor
 		~Buffer() throw()
 		{
 			clear();
@@ -66,37 +82,71 @@
 			_count  = count;
 		}
 
+		//! Removes all buffered items
 		void clear() throw()
 		{
 			destruct(_buffer, _count);
 			_count = 0;
 		}
 
+		//! Returns the number of buffered items
 		inline size_t size() const throw()
 		{ return _count; }
 
+		//! Resize the buffer
+		/*!
+			Resizes the buffer to the given size which may be greater
+			or smaller than the current. The new size must be greater or
+			equal to the current number of buffered items or a OverrunError
+			will be thrown.
+			\param sz the new size of the buffer
+			\throw OverrunError
+		*/
 		void resize(size_t sz) throw(OverrunError)
 		{
+			sz = max((size_t)1, sz);
+
 			if(_count > sz)
 				throw OverrunError("Buffer overrun", P_SOURCEINFO);
+			else if(_size == sz)
+				return;
 
-			Type* newBuffer = (Type*)new char[sizeof(Type) * sz];
-			copy_construct(newBuffer, _buffer, _count);
+			ScopedArrayPtr<char> newBuffer(new char[sizeof(Type) * sz]);
+			copy_construct((Type*)newBuffer.get(), _buffer, _count);
 			destruct(_buffer, _count);
 			delete[] (char*)_buffer;
-			_buffer = newBuffer;
+			_buffer = (Type*)newBuffer.release();
 			_size   = sz;
 		}
 
+		//! Enable or disable automatic buffer resize
+		inline void setAutoResize(bool resize) throw()
+		{ _autoResize = resize; }
+
+		//! Test if the buffer resizes automatically
+		inline bool isAutoResize() const throw()
+		{ return _autoResize; }
+
+		//! Returns the size of the buffer
 		inline size_t capacity() const throw()
 		{ return _size; }
 
+		//! Test if the buffer is empty
 		inline bool empty() const throw()
 		{ return _count == 0; }
 
+		//! Returns a pointer to the buffered items
 		inline Type* data() throw()
 		{ return _buffer; }
 
+		//! Remove items from the buffer
+		/*!
+			Removes the given number of items from the front of the buffer.
+			If the number of currently stored items is less than <count>,
+			a UnderrunError will be thrown.
+			\param count the number of items to remove from the buffer
+			\throw UnderrunError
+		*/
 		void pop(size_t count) throw(UnderrunError)
 		{
 			if(_count >= count)
@@ -110,6 +160,15 @@
 			throw UnderrunError("Buffer underrun", P_SOURCEINFO);
 		}
 
+		//! Add items to the buffer
+		/*!
+			Append the given number of items to the buffer. If the buffer is
+			to small to hold the number of items, the buffer will grow if
+			auto-resizing is enabled. Otherwise a OverrunError will be thrown.
+			\param buff pointer to the items to append
+			\param count number of items to append
+			\throw OverrunError
+		*/
 		void push(const Type* buff, size_t count) throw(OverrunError)
 		{
 			if(_size < _count + count)