Browse Source

Documented Vector

Thomas Buck 10 years ago
parent
commit
5988b8acb7
1 changed files with 210 additions and 208 deletions
  1. 210
    208
      include/Vector.h

+ 210
- 208
include/Vector.h View File

@@ -1,25 +1,9 @@
1
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
2
-/*================================================================
1
+/*!
2
+ * \file include/Vector.h
3
+ * \brief Template Vector
3 4
  *
4
- * Project : Freyja
5
- * Author  : Mongoose
6
- * Website : http://www.westga.edu/~stu7440/
7
- * Email   : stu7440@westga.edu
8
- * Object  : Vector
9
- * License : No use w/o permission (C) 2002 Mongoose
10
- * Comments: mtk template vector
11
- *
12
- *           UINT_MAX is an error condition, used in place of -1
13
- *
14
- *           This file was generated using Mongoose's C++
15
- *           template generator script.  <stu7440@westga.edu>
16
- *
17
- *-- History ------------------------------------------------
18
- *
19
- * 2002.08.31:
20
- * Mongoose - Created
21
- ================================================================*/
22
-
5
+ * \author Mongoose
6
+ */
23 7
 
24 8
 #ifndef _VECTOR_H_
25 9
 #define _VECTOR_H_
@@ -31,209 +15,211 @@
31 15
 #include <memory_test.h>
32 16
 #endif
33 17
 
34
-
35
-template <class Object> class Vector
36
-{
18
+/*!
19
+ * \brief Template class for a (pretty strange) Vector
20
+ * \tparam Object datatype the Vector can store
21
+ */
22
+template <class Object> class Vector {
37 23
 public:
38 24
 
39
-    Vector()
40
-    {
25
+    /*!
26
+     * \brief Construct an empty Vector
27
+     */
28
+    Vector() {
41 29
         mData = 0x0;
42 30
         mError = 0x0;
43
-
44 31
         mReserve = 0;
45 32
         mStart = 0;
46 33
         mEnd = 0;
47
-
48 34
         mIndex = 0;
49 35
     }
50 36
 
51
-
52
-    Vector(Vector &vector)
53
-    {
37
+    /*!
38
+     * \brief Construct a Vector from another one
39
+     * \param vector Vector to copy from
40
+     */
41
+    Vector(Vector &vector) {
54 42
         mData = 0x0;
55 43
         mError = 0x0;
56
-
57 44
         mReserve = 0;
58 45
         mStart = 0;
59 46
         mEnd = 0;
60
-
61 47
         copy(vector);
62 48
     }
63 49
 
64
-
65
-    Vector(unsigned int size)
66
-    {
50
+    /*!
51
+     * \brief Construct a Vector with a specific size
52
+     * \param size initial size
53
+     */
54
+    Vector(unsigned int size) {
67 55
         mData = 0x0;
68 56
         mError = 0x0;
69
-
70 57
         mReserve = 0;
71 58
         mStart = 0;
72 59
         mEnd = 0;
73
-
74 60
         mIndex = 0;
75
-
76 61
         resize(size);
77 62
     }
78 63
 
79
-
80
-    ~Vector()
81
-    {
64
+    /*!
65
+     * \brief Deconstruct a Vector
66
+     */
67
+    ~Vector() {
82 68
         if (!empty() && mData)
83
-        {
84 69
             delete [] mData;
85
-        }
86
-
87 70
         clear();
88 71
         mReserve = 0;
89 72
     }
90 73
 
91
-
92
-    void clear()
93
-    {
74
+    /*!
75
+     * \brief Clears the Vector, but deletes nothing
76
+     * \sa Vector::erase()
77
+     */
78
+    void clear() {
94 79
         mStart = 0;
95 80
         mEnd = 0;
96
-
97 81
         mIndex = 0;
98 82
     }
99 83
 
100
-
101
-    void erase()
102
-    {
103
-        for (start(); forward(); next())
104
-        {
84
+    /*!
85
+     * \brief Clears the vector and deletes everything contained
86
+     * \sa Vector::clear()
87
+     */
88
+    void erase() {
89
+        for (start(); forward(); next()) {
105 90
             if (current())
106
-            {
107 91
                 delete current();
108
-            }
109 92
         }
110
-
111 93
         clear();
112 94
     }
113 95
 
114
-
115
-    void reserve(unsigned int count)
116
-    {
117
-        unsigned int i;
96
+    /*!
97
+     * \brief Reserve more memory
98
+     * \param count new maximum size
99
+     */
100
+    void reserve(unsigned int count) {
118 101
         Object *swap = 0x0;
119
-
120
-
121
-        if (count > mReserve)
122
-        {
102
+        if (count > mReserve) {
123 103
             swap = mData;
124 104
             mReserve = count;
125 105
             mData = new Object[count];
126 106
         }
127
-
128
-        if (swap)
129
-        {
130
-            for (i = begin(); i < end(); ++i)
131
-            {
107
+        if (swap) {
108
+            for (unsigned int i = begin(); i < end(); ++i)
132 109
                 mData[i] = swap[i];
133
-            }
134
-
135 110
             delete [] swap;
136 111
         }
137 112
     }
138 113
 
139
-
140
-    void resize(unsigned int count)
141
-    {
114
+    /*!
115
+     * \brief Resize the Vector
116
+     * \param count new size
117
+     */
118
+    void resize(unsigned int count) {
142 119
         resize(count, 0x0);
143 120
     }
144 121
 
145
-
146
-    void resize(unsigned int count, Object object)
147
-    {
148
-        unsigned int i;
149
-
150
-
122
+    /*!
123
+     * \brief Resize the Vector
124
+     * \param count new size
125
+     * \param object what to put into blank spaces
126
+     */
127
+    void resize(unsigned int count, Object object) {
151 128
         reserve(count);
152
-
153
-        for (i = 0; i < count; ++i)
154
-        {
129
+        for (unsigned int i = 0; i < count; ++i) {
155 130
             if (i < begin() || i >= end())
156
-            {
157 131
                 mData[i] = object;
158
-            }
159 132
         }
160
-
161 133
         mEnd = count;
162 134
     }
163 135
 
164
-
165
-    void pushBack()
166
-    {
136
+    /*!
137
+     * \brief Increase size by 1
138
+     */
139
+    void pushBack() {
167 140
         pushBack(0x0);
168 141
     }
169 142
 
170
-
171
-    void pushBack(Object object)
172
-    {
143
+    /*!
144
+     * \brief Increase size by 1
145
+     * \param object what to put into new space
146
+     */
147
+    void pushBack(Object object) {
173 148
         resize(size() + 1);
174 149
         mData[size()-1] = object;
175 150
     }
176 151
 
177
-
178
-    bool empty()
179
-    {
152
+    /*!
153
+     * \brief Check if empty
154
+     * \returns true if begin() equals end()
155
+     */
156
+    bool empty() {
180 157
         return (begin() == end());
181 158
     }
182 159
 
183
-
184
-    unsigned int capacity()
185
-    {
160
+    /*!
161
+     * \brief Check maximum capacity
162
+     * \returns reserved memory
163
+     */
164
+    unsigned int capacity() {
186 165
         return mReserve;
187 166
     }
188 167
 
189
-
190
-    unsigned int begin()
191
-    {
168
+    /*!
169
+     * \brief Get start index
170
+     * \returns start index
171
+     */
172
+    unsigned int begin() {
192 173
         return mStart;
193 174
     }
194 175
 
195
-
196
-    unsigned int end()
197
-    {
176
+    /*!
177
+     * \brief Get end index
178
+     * \returns end index
179
+     */
180
+    unsigned int end() {
198 181
         return mEnd;
199 182
     }
200 183
 
201
-
202
-    unsigned int size()
203
-    {
184
+    /*!
185
+     * \brief Get size
186
+     * \returns end index
187
+     */
188
+    unsigned int size() {
204 189
         return mEnd;
205 190
     }
206 191
 
207
-
208
-    void copy(Vector<Object> &vector)
209
-    {
192
+    /*!
193
+     * \brief Copy a Vector into this one.
194
+     * May increase size.
195
+     * \param vector Vector to copy from
196
+     */
197
+    void copy(Vector<Object> &vector) {
210 198
         unsigned int i;
211
-
212
-
213
-        if (vector.capacity() > capacity())
214
-        {
199
+        if (vector.capacity() > capacity()) {
215 200
             resize(vector.capacity());
216 201
         }
217
-
218 202
         mStart = vector.begin();
219 203
         mEnd = vector.end();
220
-
221
-        for (i = vector.begin(); i < vector.end(); ++i)
222
-        {
204
+        for (i = vector.begin(); i < vector.end(); ++i) {
223 205
             mData[i] = vector[i];
224
-            //Add(list->Current()); // WTFBBQ?
225 206
         }
226 207
     }
227 208
 
228
-
229
-    void qSort(int (*compareFunc)(const void *, const void *))
230
-    {
209
+    /*!
210
+     * \brief Sort the Vector
211
+     * \param compareFunc comparison function for qsort
212
+     */
213
+    void qSort(int (*compareFunc)(const void *, const void *)) {
231 214
         qsort(mData, end(), sizeof(Object), compareFunc);
232 215
     }
233 216
 
234
-
235
-    void swap(unsigned int index, unsigned int index2)
236
-    {
217
+    /*!
218
+     * \brief Swap two items
219
+     * \param index first index
220
+     * \param index2 second index
221
+     */
222
+    void swap(unsigned int index, unsigned int index2) {
237 223
         if (index < begin() || index > end())
238 224
             return;
239 225
 
@@ -245,46 +231,45 @@ public:
245 231
         mData[index2] = swap;
246 232
     }
247 233
 
248
-
249
-    void assign(unsigned int index, Object object)
250
-    {
234
+    /*!
235
+     * \brief Set an index to a value
236
+     * \param index index to set
237
+     * \param object object to set it to
238
+     */
239
+    void assign(unsigned int index, Object object) {
251 240
         mData[index] = object;
252 241
     }
253 242
 
254
-
255
-    Object operator [] (unsigned int index)
256
-    {
257
-        if (mData == 0x0 || index < begin() || index > end() ||
258
-             index >= size() || empty())
243
+    /*!
244
+     * \brief Get value at index
245
+     * \param index index to look at
246
+     * \returns data for index, or error object
247
+     */
248
+    Object operator [] (unsigned int index) {
249
+        if (mData == 0x0 || index < begin() || index > end() || index >= size() || empty())
259 250
             return mError;
260
-
261 251
         return mData[index];
262 252
     }
263 253
 
264
-
265
-    void print(void (*print_func)(Object))
266
-    {
267
-        unsigned int i;
268
-
269
-
270
-        for (i = begin(); i < end(); ++i)
271
-        {
254
+    /*!
255
+     * \brief Print the Vector
256
+     * \param print_func function that can print Objects
257
+     */
258
+    void print(void (*print_func)(Object)) {
259
+        for (unsigned int i = begin(); i < end(); ++i) {
272 260
             if (print_func)
273
-            {
274 261
                 (*print_func)(mData[i]);
275
-            }
276
-
277 262
             fflush(stdout);
278 263
         }
279
-
280 264
         printf("\n");
281 265
     }
282 266
 
283 267
 
284
-    // Built-in iterator methods ////////////////////////////////
285
-
286
-    void start(unsigned int index)
287
-    {
268
+    /*!
269
+     * \brief Start Iterator at specific index
270
+     * \param index where to start
271
+     */
272
+    void start(unsigned int index) {
288 273
         if (mData == 0x0 || index < begin() || index > end() ||
289 274
              index >= size() || empty())
290 275
             return;
@@ -292,88 +277,107 @@ public:
292 277
         mIndex = index;
293 278
     }
294 279
 
295
-    void start()
296
-    {
280
+    /*!
281
+     * \brief Set Iterator to the first element
282
+     */
283
+    void start() {
297 284
         mIndex = begin();
298 285
     }
299 286
 
300
-
301
-    void finish()
302
-    {
287
+    /*!
288
+     * \brief Set Iterator to the last element
289
+     */
290
+    void finish() {
303 291
         mIndex = end() - 1;
304 292
     }
305 293
 
306
-
307
-    bool forward()
308
-    {
294
+    /*!
295
+     * \brief Check if the Iterator can go forward
296
+     * \returns true if Iterator is still in range
297
+     */
298
+    bool forward() {
309 299
         return (mIndex < end());
310 300
     }
311 301
 
312
-
313
-    bool backward()
314
-    {
302
+    /*!
303
+     * \brief Check if the Iterator can go backwards
304
+     * \returns true if Iterator is already in range
305
+     */
306
+    bool backward() {
315 307
         return (mIndex + 1 > begin());
316 308
     }
317 309
 
318
-
319
-    void next()
320
-    {
310
+    /*!
311
+     * \brief Increment the Iterator
312
+     */
313
+    void next() {
321 314
         if (mIndex < end())
322 315
             ++mIndex;
323 316
     }
324 317
 
325
-    void prev()
326
-    {
318
+    /*!
319
+     * \brief Decrement the Iterator
320
+     */
321
+    void prev() {
327 322
         --mIndex;
328 323
     }
329 324
 
330
-
331
-    void setError(Object object)
332
-    {
325
+    /*!
326
+     * \brief Set the error object
327
+     * \param object new error object
328
+     */
329
+    void setError(Object object) {
333 330
         mError = object;
334 331
     }
335 332
 
336
-
337
-    unsigned int getCurrentIndex()
338
-    {
333
+    /*!
334
+     * \brief Get Iterator index
335
+     * \returns current Iterator index
336
+     */
337
+    unsigned int getCurrentIndex() {
339 338
         return mIndex;
340 339
     }
341 340
 
342
-
343
-    unsigned int setCurrentIndex(unsigned int index)
344
-    {
341
+    /*!
342
+     * \brief Set Iterator index
343
+     * \param index new Iterator index
344
+     */
345
+    void setCurrentIndex(unsigned int index) {
345 346
         if (index < end())
346
-        {
347 347
             mIndex = index;
348
-        }
349 348
     }
350 349
 
351
-
352
-    Object current()
353
-    {
350
+    /*!
351
+     * \brief Get current element
352
+     * \returns element at Iterator index
353
+     */
354
+    Object current() {
354 355
         return mData[mIndex];
355 356
     }
356 357
 
357
-
358
-    /* Requires objects to support '=='  */
359
-    bool find(Object object)
360
-    {
361
-        for (start(); forward(); next())
362
-        {
358
+    /*!
359
+     * \brief Check if an object is in the Vector.
360
+     * Requires objects to support `==`.
361
+     * \param object object to find
362
+     * \returns true if found, false if not.
363
+     */
364
+    bool find(Object object) {
365
+        for (start(); forward(); next()) {
363 366
             if (object == current())
364
-            {
365 367
                 return true;
366
-            }
367 368
         }
368
-
369 369
         return false;
370 370
     }
371 371
 
372
-    // Instead of appending objects this apptempts replacing 'removed' objects
373
-    unsigned int add(Object object)
374
-    {
375
-        if (begin() > 0)
376
-        {
372
+    //
373
+    /*!
374
+     * \brief Add an object.
375
+     * Instead of appending objects this attempts replacing 'removed' objects.
376
+     * \param object object to add
377
+     * \returns index of added object
378
+     */
379
+    unsigned int add(Object object) {
380
+        if (begin() > 0) {
377 381
             mData[begin() - 1] = object;
378 382
             --mStart;
379 383
 
@@ -385,24 +389,22 @@ public:
385 389
     }
386 390
 
387 391
 
388
-    // Hhhmm... dangerous and fun - this gets your data out of order
389
-    void remove(unsigned int index)
390
-    {
392
+    /*!
393
+     * \brief Remove an object. This will change the index of another element!
394
+     * \param index index to "remove".
395
+     */
396
+    void remove(unsigned int index) {
391 397
         mData[index] = mData[begin()];
392 398
         ++mStart;
393 399
     }
394 400
 
395 401
 private:
396
-
397
-    Object *mData;
398
-
399
-    Object mError;
400
-
401
-    unsigned int mReserve;
402
-    unsigned int mStart;
403
-    unsigned int mEnd;
404
-
405
-    unsigned int mIndex;
402
+    Object *mData;         //!< Data array
403
+    Object mError;         //!< Error object
404
+    unsigned int mReserve; //!< Index for reserved space
405
+    unsigned int mStart;   //!< Start index
406
+    unsigned int mEnd;     //!< End index
407
+    unsigned int mIndex;   //!< Iterator index
406 408
 };
407 409
 
408 410
 #endif

Loading…
Cancel
Save