Mercurial > almixer_isolated

comparison CircularQueue.h @ 1:a8a8fe374984

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Subversion era
author Eric Wing <ewing . public |-at-| gmail . com>
date Wed, 27 Oct 2010 16:51:16 -0700
parents 01e39f9f58d5
children 279d0427ef26
comparison
equal deleted inserted replaced
0:01e39f9f58d5 1:a8a8fe374984
91 * CircularQueueUnsignedInt_Print(myqueue); 91 * CircularQueueUnsignedInt_Print(myqueue);
92 * 92 *
93 * @endcode 93 * @endcode
94 */ 94 */
95 95
96 /* This is a trick I picked up from Lua. Doing the typedef separately
97 * (and I guess before the definition) instead of a single
98 * entry: typedef struct {...} YourName; seems to allow me
99 * to use forward declarations. Doing it the other way (like SDL)
100 * seems to prevent me from using forward declarions as I get conflicting
101 * definition errors. I don't really understand why though.
102 */
103 typedef struct CircularQueueUnsignedInt CircularQueueUnsignedInt;
96 /** 104 /**
97 * This is the essentially the CircularQueue object. 105 * This is the essentially the CircularQueue object.
98 * This contains all the data associated with a CircularQueue instance. 106 * This contains all the data associated with a CircularQueue instance.
99 * This version is for unsigned int data types. In the future, I suppose 107 * This version is for unsigned int data types. In the future, I suppose
100 * I could add a void* data type at the very least and maybe some 108 * I could add a void* data type at the very least and maybe some
101 * other data types. 109 * other data types.
102 * This should be considered an opaque data type. 110 * This should be considered an opaque data type.
103 */ 111 */
104 typedef struct 112 struct CircularQueueUnsignedInt
105 { 113 {
106 unsigned int maxSize; /**< Max size of the queue. */ 114 unsigned int maxSize; /**< Max size of the queue. */
107 unsigned int currentSize; /**< Current number of entries in the queue. */ 115 unsigned int currentSize; /**< Current number of entries in the queue. */
108 unsigned int headIndex; /**< The index of where the current head is. */ 116 unsigned int headIndex; /**< The index of where the current head is. */
109 unsigned int tailIndex; /**< The index of where the current tail is. */ 117 unsigned int tailIndex; /**< The index of where the current tail is. */
110 unsigned int* internalQueue; /**< The array representing the queue. */ 118 unsigned int* internalQueue; /**< The array representing the queue. */
111 } CircularQueueUnsignedInt; 119 };
112 120
113 /** 121 /**
114 * This creates a new CircularQueue (for unsigned int) instance. 122 * This creates a new CircularQueue (for unsigned int) instance.
115 * This will create a new circular queue instance which holds 123 * This will create a new circular queue instance which holds
116 * unsigned int's in its queue. 124 * unsigned int's in its queue.
264 * 272 *
265 * @param queue The pointer to the CircularQueue instance. 273 * @param queue The pointer to the CircularQueue instance.
266 */ 274 */
267 void CircularQueueUnsignedInt_Print(CircularQueueUnsignedInt* queue); 275 void CircularQueueUnsignedInt_Print(CircularQueueUnsignedInt* queue);
268 276
269 277 /**
278 * This returns the element located at the specified index,
279 * where index=0 represents the head/front of the queue.
280 *
281 * @param queue The pointer to the CircularQueue instance.
282 * @param the_index The index of the element you want where 0 represents the
283 * head/front of the queue and Size-1 is the back.
284 *
285 * @return Returns the value located at the index on success, or 0 on failure.
286 * Be careful to not to confuse an error for a legitmate 0 value.
287 * Any index from 0 to Size-1 (where Size>0) will be a valid index.
288 *
289 * This example traverses through the whole queue and prints out each value.
290 * @code
291 * fprintf(stderr, "Queue: ");
292 * for(i=0;i<CircularQueueUnsignedInt_Size(xValueQueue);i++)
293 * {
294 * ret_val = CircularQueueUnsignedInt_ValueAtIndex(xValueQueue, i);
295 * fprintf(stderr, "%d ", ret_val);
296 *
297 * }
298 * fprintf(stderr, "\n");
299 *
300 * @note The implementation uses a modulo operation to compute the index, so
301 * this may not be the speediest operation in a tight loop.
302 * This implementation was not optimized for random access, though it still
303 * is technically O(1).
304 *
305 */
306 unsigned int CircularQueueUnsignedInt_ValueAtIndex(CircularQueueUnsignedInt* queue, unsigned int the_index);
307
308
309 /* This is a trick I picked up from Lua. Doing the typedef separately
310 * (and I guess before the definition) instead of a single
311 * entry: typedef struct {...} YourName; seems to allow me
312 * to use forward declarations. Doing it the other way (like SDL)
313 * seems to prevent me from using forward declarions as I get conflicting
314 * definition errors. I don't really understand why though.
315 */
316 typedef struct CircularQueueVoid CircularQueueVoid;
270 /** 317 /**
271 * This is the essentially the CircularQueue object. 318 * This is the essentially the CircularQueue object.
272 * This contains all the data associated with a CircularQueue instance. 319 * This contains all the data associated with a CircularQueue instance.
273 * This version is for unsigned int data types. In the future, I suppose 320 * This version is for unsigned int data types. In the future, I suppose
274 * I could add a void* data type at the very least and maybe some 321 * I could add a void* data type at the very least and maybe some
275 * other data types. 322 * other data types.
276 * This should be considered an opaque data type. 323 * This should be considered an opaque data type.
277 */ 324 */
278 typedef struct 325 struct CircularQueueVoid
279 { 326 {
280 unsigned int maxSize; /**< Max size of the queue. */ 327 unsigned int maxSize; /**< Max size of the queue. */
281 unsigned int currentSize; /**< Current number of entries in the queue. */ 328 unsigned int currentSize; /**< Current number of entries in the queue. */
282 unsigned int headIndex; /**< The index of where the current head is. */ 329 unsigned int headIndex; /**< The index of where the current head is. */
283 unsigned int tailIndex; /**< The index of where the current tail is. */ 330 unsigned int tailIndex; /**< The index of where the current tail is. */
284 void** internalQueue; /**< The array representing the queue. */ 331 void** internalQueue; /**< The array representing the queue. */
285 } CircularQueueVoid; 332 };
286 333
287 /** 334 /**
288 * This creates a new CircularQueue (for void* ) instance. 335 * This creates a new CircularQueue (for void* ) instance.
289 * This will create a new circular queue instance which holds 336 * This will create a new circular queue instance which holds
290 * unsigned int's in its queue. 337 * unsigned int's in its queue.
427 * 474 *
428 * @param queue The pointer to the CircularQueue instance. 475 * @param queue The pointer to the CircularQueue instance.
429 */ 476 */
430 void CircularQueueVoid_Clear(CircularQueueVoid* queue); 477 void CircularQueueVoid_Clear(CircularQueueVoid* queue);
431 478
432 /* Not implemented for void* */ 479 /**
433 /* 480 * This is a debugging function that will print all the addresses
481 * of elements in the queue to stderr.
482 * This function is provided as convenience, but should not be considered
483 * as part of the standard API. Treat this function as deprecated
484 * as it's implementation may change or be removed entirely.
485 *
486 * @param queue The pointer to the CircularQueue instance.
487 */
434 void CircularQueueVoid_Print(CircularQueueVoid* queue); 488 void CircularQueueVoid_Print(CircularQueueVoid* queue);
435 */ 489
490 /**
491 * This returns the element located at the specified index,
492 * where index=0 represents the head/front of the queue.
493 *
494 * @param queue The pointer to the CircularQueue instance.
495 * @param the_index The index of the element you want where 0 represents the
496 * head/front of the queue and Size-1 is the back.
497 *
498 * @return Returns the element located at the index on success, or NULL on failure.
499 * Be careful to not to confuse an error for a legitmate NULL value.
500 * Any index from 0 to Size-1 (where Size>0) will be a valid index.
501 *
502 * This example traverses through the whole queue and prints out each value.
503 * @code
504 * fprintf(stderr, "Queue: ");
505 * for(i=0;i<CircularQueueVoid_ValueAtIndex(xValueQueue);i++)
506 * {
507 * void* ret_val = CircularQueueUnsignedInt_ValueAtIndex(xValueQueue, i);
508 * fprintf(stderr, "%x ", ret_val);
509 *
510 * }
511 * fprintf(stderr, "\n");
512 *
513 * @note The implementation uses a modulo operation to compute the index, so
514 * this may not be the speediest operation in a tight loop.
515 * This implementation was not optimized for random access, though it still
516 * is technically O(1).
517 *
518 */
519 void* CircularQueueVoid_ValueAtIndex(CircularQueueVoid* queue, unsigned int the_index);
436 520
437 521
438 522
439 523
440 /* Ends C function definitions when using C++ */ 524 /* Ends C function definitions when using C++ */