From 0e5b590c8332c114cea021d759da627cd22ae53a Mon Sep 17 00:00:00 2001
From: Skidd13 <skidd13@gmx.de>
Date: Fri, 5 Feb 2010 16:50:32 +0100
Subject: [PATCH 2/4] -Doc: SmallArray
 -Codechange: Apply coding style and add this where appropriate

---
 src/misc/array.hpp |  108 ++++++++++++++++++++++++++++++++++++++-------------
 1 files changed, 80 insertions(+), 28 deletions(-)

diff --git a/src/misc/array.hpp b/src/misc/array.hpp
index 1da5027..798daee 100644
--- a/src/misc/array.hpp
+++ b/src/misc/array.hpp
@@ -15,65 +15,117 @@
 #include "fixedsizearray.hpp"
 #include "str.hpp"
 
-/** Flexible array with size limit. Implemented as fixed size
- *  array of fixed size arrays */
+/**
+ * Flexible array with deferred block allocation and size limit.
+ * Implemented as fixed size array of fixed size arrays. The way
+ * the fixed size array is implemented results in a small
+ * SuperArray. It contains more or less only the pointers to the
+ * SubArray memory blocks. The allocation of each SubArray's
+ * memory is deferred until needed.
+ *
+ * @tparam T The type of the items stored
+ * @tparam B The size of the SubArray
+ * @tparam N The number of SubArrays in the array
+ */
 template <typename T, uint B = 1024, uint N = B>
 class SmallArray {
 protected:
-	typedef FixedSizeArray<T, B> SubArray; ///< inner array
-	typedef FixedSizeArray<SubArray, N> SuperArray; ///< outer array
+	typedef FixedSizeArray<T, B> SubArray;          ///< (inner array) array type to carry data
+	typedef FixedSizeArray<SubArray, N> SuperArray; ///< (outer array) array type to carry the SubArrays
 
 	static const uint Tcapacity = B * N; ///< total max number of items
 
 	SuperArray data; ///< array of arrays of items
 
-	/** return first sub-array with free space for new item */
-	FORCEINLINE SubArray& FirstFreeSubArray()
+	/**
+	 * Get the first SubArray with space for an item.
+	 * If there isn't any create one.
+	 *
+	 * @return reference to the first free SubArray
+	 */
+	FORCEINLINE SubArray &FirstFreeSubArray()
 	{
-		uint super_size = data.Length();
+		uint super_size = this->data.Length();
 		if (super_size > 0) {
-			SubArray& s = data[super_size - 1];
+			SubArray &s = this->data[super_size - 1];
 			if (!s.IsFull()) return s;
 		}
-		return *data.AppendC();
+		return *this->data.AppendC();
 	}
 
 public:
 	/** implicit constructor */
 	FORCEINLINE SmallArray() { }
+
 	/** Clear (destroy) all items */
-	FORCEINLINE void Clear() {data.Clear();}
+	FORCEINLINE void Clear() { this->data.Clear(); }
+
 	/** Return actual number of items */
 	FORCEINLINE uint Length() const
 	{
-		uint super_size = data.Length();
+		uint super_size = this->data.Length();
 		if (super_size == 0) return 0;
-		uint sub_size = data[super_size - 1].Length();
+		uint sub_size = this->data[super_size - 1].Length();
 		return (super_size - 1) * B + sub_size;
 	}
-	/** return true if array is empty */
+
+	/**
+	 * Tests whether the array is empty.
+	 *
+	 * @return true if array is empty
+	 */
 	FORCEINLINE bool IsEmpty() { return data.IsEmpty(); }
-	/** return true if array is full */
-	FORCEINLINE bool IsFull() { return data.IsFull() && data[N - 1].IsFull(); }
-	/** allocate but not construct new item */
-	FORCEINLINE T *Append() { return FirstFreeSubArray().Append(); }
-	/** allocate and construct new item */
-	FORCEINLINE T *AppendC() { return FirstFreeSubArray().AppendC(); }
-	/** indexed access (non-const) */
-	FORCEINLINE T& operator [] (uint index)
+
+	/**
+	 * Tests whether the array is full.
+	 *
+	 * @return true if array is full
+	 */
+	FORCEINLINE bool IsFull() { return this->data.IsFull() && this->data[N - 1].IsFull(); }
+
+	/**
+	* Append ("allocate"), but don't construct an item
+	* and return it.
+	*
+	* @return pointer to the memory of the new item
+	*/
+	FORCEINLINE T *Append() { return this->FirstFreeSubArray().Append(); }
+
+	/**
+	 * Append ("allocate") and construct new item and
+	 * return it.
+	 *
+	 * @return pointer to the new item
+	 */
+	FORCEINLINE T *AppendC() { return this->FirstFreeSubArray().AppendC(); }
+
+	/**
+	 * Get item "number"
+	 *
+	 * @param index the positon of the item
+	 * @return the item
+	 */
+	FORCEINLINE T &operator[](uint index)
 	{
-		SubArray& s = data[index / B];
-		T& item = s[index % B];
+		SubArray &s = this->data[index / B];
+		T &item = s[index % B];
 		return item;
 	}
-	/** indexed access (const) */
-	FORCEINLINE const T& operator [] (uint index) const
+
+	/**
+	 * Get item "number" (const)
+	 *
+	 * @param index the positon of the item
+	 * @return the item
+	 */
+	FORCEINLINE const T &operator[](uint index) const
 	{
-		const SubArray& s = data[index / B];
-		const T& item = s[index % B];
+		const SubArray &s = this->data[index / B];
+		const T &item = s[index % B];
 		return item;
 	}
 
+	/** Dump item data ?? */
 	template <typename D> void Dump(D &dmp) const
 	{
 		dmp.WriteLine("capacity = %d", Tcapacity);
@@ -81,7 +133,7 @@ public:
 		dmp.WriteLine("num_items = %d", num_items);
 		CStrA name;
 		for (uint i = 0; i < num_items; i++) {
-			const T& item = (*this)[i];
+			const T &item = (*this)[i];
 			name.Format("item[%d]", i);
 			dmp.WriteStructT(name.Data(), &item);
 		}
-- 
1.6.6