Documented Vector

include/Vector.h

@@ -1,25 +1,9 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file include/Vector.h
+ * \brief Template Vector
  *
- * Project : Freyja
- * Author  : Mongoose
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : Vector
- * License : No use w/o permission (C) 2002 Mongoose
- * Comments: mtk template vector
- *
- *           UINT_MAX is an error condition, used in place of -1
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History ------------------------------------------------
- *
- * 2002.08.31:
- * Mongoose - Created
- ================================================================*/
-
+ * \author Mongoose
+ */
 
 #ifndef _VECTOR_H_
 #define _VECTOR_H_
@@ -31,209 +15,211 @@
 #include <memory_test.h>
 #endif
 
-
-template <class Object> class Vector
-{
+/*!
+ * \brief Template class for a (pretty strange) Vector
+ * \tparam Object datatype the Vector can store
+ */
+template <class Object> class Vector {
 public:
 
-    Vector()
-    {
+    /*!
+     * \brief Construct an empty Vector
+     */
+    Vector() {
         mData = 0x0;
         mError = 0x0;
-
         mReserve = 0;
         mStart = 0;
         mEnd = 0;
-
         mIndex = 0;
     }
 
-
-    Vector(Vector &vector)
-    {
+    /*!
+     * \brief Construct a Vector from another one
+     * \param vector Vector to copy from
+     */
+    Vector(Vector &vector) {
         mData = 0x0;
         mError = 0x0;
-
         mReserve = 0;
         mStart = 0;
         mEnd = 0;
-
         copy(vector);
     }
 
-
-    Vector(unsigned int size)
-    {
+    /*!
+     * \brief Construct a Vector with a specific size
+     * \param size initial size
+     */
+    Vector(unsigned int size) {
         mData = 0x0;
         mError = 0x0;
-
         mReserve = 0;
         mStart = 0;
         mEnd = 0;
-
         mIndex = 0;
-
         resize(size);
     }
 
-
-    ~Vector()
-    {
+    /*!
+     * \brief Deconstruct a Vector
+     */
+    ~Vector() {
         if (!empty() && mData)
-        {
             delete [] mData;
-        }
-
         clear();
         mReserve = 0;
     }
 
-
-    void clear()
-    {
+    /*!
+     * \brief Clears the Vector, but deletes nothing
+     * \sa Vector::erase()
+     */
+    void clear() {
         mStart = 0;
         mEnd = 0;
-
         mIndex = 0;
     }
 
-
-    void erase()
-    {
-        for (start(); forward(); next())
-        {
+    /*!
+     * \brief Clears the vector and deletes everything contained
+     * \sa Vector::clear()
+     */
+    void erase() {
+        for (start(); forward(); next()) {
             if (current())
-            {
                 delete current();
-            }
         }
-
         clear();
     }
 
-
-    void reserve(unsigned int count)
-    {
-        unsigned int i;
+    /*!
+     * \brief Reserve more memory
+     * \param count new maximum size
+     */
+    void reserve(unsigned int count) {
         Object *swap = 0x0;
-
-
-        if (count > mReserve)
-        {
+        if (count > mReserve) {
             swap = mData;
             mReserve = count;
             mData = new Object[count];
         }
-
-        if (swap)
-        {
-            for (i = begin(); i < end(); ++i)
-            {
+        if (swap) {
+            for (unsigned int i = begin(); i < end(); ++i)
                 mData[i] = swap[i];
-            }
-
             delete [] swap;
         }
     }
 
-
-    void resize(unsigned int count)
-    {
+    /*!
+     * \brief Resize the Vector
+     * \param count new size
+     */
+    void resize(unsigned int count) {
         resize(count, 0x0);
     }
 
-
-    void resize(unsigned int count, Object object)
-    {
-        unsigned int i;
-
-
+    /*!
+     * \brief Resize the Vector
+     * \param count new size
+     * \param object what to put into blank spaces
+     */
+    void resize(unsigned int count, Object object) {
         reserve(count);
-
-        for (i = 0; i < count; ++i)
-        {
+        for (unsigned int i = 0; i < count; ++i) {
             if (i < begin() || i >= end())
-            {
                 mData[i] = object;
-            }
         }
-
         mEnd = count;
     }
 
-
-    void pushBack()
-    {
+    /*!
+     * \brief Increase size by 1
+     */
+    void pushBack() {
         pushBack(0x0);
     }
 
-
-    void pushBack(Object object)
-    {
+    /*!
+     * \brief Increase size by 1
+     * \param object what to put into new space
+     */
+    void pushBack(Object object) {
         resize(size() + 1);
         mData[size()-1] = object;
     }
 
-
-    bool empty()
-    {
+    /*!
+     * \brief Check if empty
+     * \returns true if begin() equals end()
+     */
+    bool empty() {
         return (begin() == end());
     }
 
-
-    unsigned int capacity()
-    {
+    /*!
+     * \brief Check maximum capacity
+     * \returns reserved memory
+     */
+    unsigned int capacity() {
         return mReserve;
     }
 
-
-    unsigned int begin()
-    {
+    /*!
+     * \brief Get start index
+     * \returns start index
+     */
+    unsigned int begin() {
         return mStart;
     }
 
-
-    unsigned int end()
-    {
+    /*!
+     * \brief Get end index
+     * \returns end index
+     */
+    unsigned int end() {
         return mEnd;
     }
 
-
-    unsigned int size()
-    {
+    /*!
+     * \brief Get size
+     * \returns end index
+     */
+    unsigned int size() {
         return mEnd;
     }
 
-
-    void copy(Vector<Object> &vector)
-    {
+    /*!
+     * \brief Copy a Vector into this one.
+     * May increase size.
+     * \param vector Vector to copy from
+     */
+    void copy(Vector<Object> &vector) {
         unsigned int i;
-
-
-        if (vector.capacity() > capacity())
-        {
+        if (vector.capacity() > capacity()) {
             resize(vector.capacity());
         }
-
         mStart = vector.begin();
         mEnd = vector.end();
-
-        for (i = vector.begin(); i < vector.end(); ++i)
-        {
+        for (i = vector.begin(); i < vector.end(); ++i) {
             mData[i] = vector[i];
-            //Add(list->Current()); // WTFBBQ?
         }
     }
 
-
-    void qSort(int (*compareFunc)(const void *, const void *))
-    {
+    /*!
+     * \brief Sort the Vector
+     * \param compareFunc comparison function for qsort
+     */
+    void qSort(int (*compareFunc)(const void *, const void *)) {
         qsort(mData, end(), sizeof(Object), compareFunc);
     }
 
-
-    void swap(unsigned int index, unsigned int index2)
-    {
+    /*!
+     * \brief Swap two items
+     * \param index first index
+     * \param index2 second index
+     */
+    void swap(unsigned int index, unsigned int index2) {
         if (index < begin() || index > end())
             return;
 
@@ -245,46 +231,45 @@ public:
         mData[index2] = swap;
     }
 
-
-    void assign(unsigned int index, Object object)
-    {
+    /*!
+     * \brief Set an index to a value
+     * \param index index to set
+     * \param object object to set it to
+     */
+    void assign(unsigned int index, Object object) {
         mData[index] = object;
     }
 
-
-    Object operator [] (unsigned int index)
-    {
-        if (mData == 0x0 || index < begin() || index > end() ||
-             index >= size() || empty())
+    /*!
+     * \brief Get value at index
+     * \param index index to look at
+     * \returns data for index, or error object
+     */
+    Object operator [] (unsigned int index) {
+        if (mData == 0x0 || index < begin() || index > end() || index >= size() || empty())
             return mError;
-
         return mData[index];
     }
 
-
-    void print(void (*print_func)(Object))
-    {
-        unsigned int i;
-
-
-        for (i = begin(); i < end(); ++i)
-        {
+    /*!
+     * \brief Print the Vector
+     * \param print_func function that can print Objects
+     */
+    void print(void (*print_func)(Object)) {
+        for (unsigned int i = begin(); i < end(); ++i) {
             if (print_func)
-            {
                 (*print_func)(mData[i]);
-            }
-
             fflush(stdout);
         }
-
         printf("\n");
     }
 
 
-    // Built-in iterator methods ////////////////////////////////
-
-    void start(unsigned int index)
-    {
+    /*!
+     * \brief Start Iterator at specific index
+     * \param index where to start
+     */
+    void start(unsigned int index) {
         if (mData == 0x0 || index < begin() || index > end() ||
              index >= size() || empty())
             return;
@@ -292,88 +277,107 @@ public:
         mIndex = index;
     }
 
-    void start()
-    {
+    /*!
+     * \brief Set Iterator to the first element
+     */
+    void start() {
         mIndex = begin();
     }
 
-
-    void finish()
-    {
+    /*!
+     * \brief Set Iterator to the last element
+     */
+    void finish() {
         mIndex = end() - 1;
     }
 
-
-    bool forward()
-    {
+    /*!
+     * \brief Check if the Iterator can go forward
+     * \returns true if Iterator is still in range
+     */
+    bool forward() {
         return (mIndex < end());
     }
 
-
-    bool backward()
-    {
+    /*!
+     * \brief Check if the Iterator can go backwards
+     * \returns true if Iterator is already in range
+     */
+    bool backward() {
         return (mIndex + 1 > begin());
     }
 
-
-    void next()
-    {
+    /*!
+     * \brief Increment the Iterator
+     */
+    void next() {
         if (mIndex < end())
             ++mIndex;
     }
 
-    void prev()
-    {
+    /*!
+     * \brief Decrement the Iterator
+     */
+    void prev() {
         --mIndex;
     }
 
-
-    void setError(Object object)
-    {
+    /*!
+     * \brief Set the error object
+     * \param object new error object
+     */
+    void setError(Object object) {
         mError = object;
     }
 
-
-    unsigned int getCurrentIndex()
-    {
+    /*!
+     * \brief Get Iterator index
+     * \returns current Iterator index
+     */
+    unsigned int getCurrentIndex() {
         return mIndex;
     }
 
-
-    unsigned int setCurrentIndex(unsigned int index)
-    {
+    /*!
+     * \brief Set Iterator index
+     * \param index new Iterator index
+     */
+    void setCurrentIndex(unsigned int index) {
         if (index < end())
-        {
             mIndex = index;
-        }
     }
 
-
-    Object current()
-    {
+    /*!
+     * \brief Get current element
+     * \returns element at Iterator index
+     */
+    Object current() {
         return mData[mIndex];
     }
 
-
-    /* Requires objects to support '=='  */
-    bool find(Object object)
-    {
-        for (start(); forward(); next())
-        {
+    /*!
+     * \brief Check if an object is in the Vector.
+     * Requires objects to support `==`.
+     * \param object object to find
+     * \returns true if found, false if not.
+     */
+    bool find(Object object) {
+        for (start(); forward(); next()) {
             if (object == current())
-            {
                 return true;
-            }
         }
-
         return false;
     }
 
-    // Instead of appending objects this apptempts replacing 'removed' objects
-    unsigned int add(Object object)
-    {
-        if (begin() > 0)
-        {
+    //
+    /*!
+     * \brief Add an object.
+     * Instead of appending objects this attempts replacing 'removed' objects.
+     * \param object object to add
+     * \returns index of added object
+     */
+    unsigned int add(Object object) {
+        if (begin() > 0) {
             mData[begin() - 1] = object;
             --mStart;
 
@@ -385,24 +389,22 @@ public:
     }
 
 
-    // Hhhmm... dangerous and fun - this gets your data out of order
-    void remove(unsigned int index)
-    {
+    /*!
+     * \brief Remove an object. This will change the index of another element!
+     * \param index index to "remove".
+     */
+    void remove(unsigned int index) {
         mData[index] = mData[begin()];
         ++mStart;
     }
 
 private:
-
-    Object *mData;
-
-    Object mError;
-
-    unsigned int mReserve;
-    unsigned int mStart;
-    unsigned int mEnd;
-
-    unsigned int mIndex;
+    Object *mData;         //!< Data array
+    Object mError;         //!< Error object
+    unsigned int mReserve; //!< Index for reserved space
+    unsigned int mStart;   //!< Start index
+    unsigned int mEnd;     //!< End index
+    unsigned int mIndex;   //!< Iterator index
 };
 
 #endif