Changeset 89 for trunk/include


Ignore:
Timestamp:
03/09/07 10:00:09 (18 years ago)
Author:
tim
Message:

Added contract comments to void_stack header. Minor cleanups in void_stack implementation.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/include/void_stack.h

    r81 r89  
    3434typedef struct _void_stack_iterator
    3535{
    36   void_stack* stack;
     36  const void_stack* stack;
    3737  unsigned short cur;
    3838} void_stack_iterator;
    3939
    4040
    41 /* XXX: need to document these interfaces */
     41/* void_stack_new():
     42 *  Allocates a new void_stack.
     43 *
     44 * Arguments:
     45 *  max_size -- the maxiumum number of elements
     46 *              which may be pushed onto the stack.
     47 *
     48 * Returns:
     49 *  a pointer to the newly allocated void_stack, or NULL if an error occurred.
     50 */
    4251void_stack* void_stack_new(unsigned short max_size);
     52
     53
     54/* void_stack_copy():
     55 *  Makes a shallow copy of void_stack.
     56 *
     57 * Arguments:
     58 *  v -- the stack to make a copy of.
     59 *
     60 * Returns:
     61 *  a pointer to the duplicate void_stack, or NULL If an error occurred.
     62 */
    4363void_stack* void_stack_copy(const void_stack* v);
     64
     65
     66/* void_stack_copy_reverse():
     67 *  Makes a shallow copy of void_stack in reverse order.
     68 *
     69 * Arguments:
     70 *  v -- the stack to make a copy of.
     71 *
     72 * Returns:
     73 *  a pointer to the duplicate void_stack (which will be in reverse order),
     74 *  or NULL If an error occurred.
     75 */
    4476void_stack* void_stack_copy_reverse(const void_stack* v);
     77
     78
     79/* void_stack_free():
     80 *  Frees the memory associated with a void_stack, but not the elements held
     81 *  on the stack.
     82 *
     83 * Arguments:
     84 *  stack -- the stack to be free()d.
     85 */
    4586void void_stack_free(void_stack* stack);
     87
     88
     89/* void_stack_free_deep():
     90 *  Frees the memory associated with a void_stack and the elements referenced
     91 *  by the stack.  Do not use this function if the elements of the stack
     92 *  are also free()d elsewhere, or contain pointers to other memory which
     93 *  cannot be otherwise free()d.
     94 *
     95 * Arguments:
     96 *  stack -- the stack to be free()d.
     97 */
    4698void void_stack_free_deep(void_stack* stack);
    47 unsigned short void_stack_size(void_stack* stack);
     99
     100
     101/* void_stack_size():
     102 *  Query the current number of elements on a void_stack()
     103 *
     104 * Arguments:
     105 *  stack -- the void_stack to query
     106 *
     107 * Returns:
     108 *  the number of elements currently on the stack.
     109 */
     110unsigned short void_stack_size(const void_stack* stack);
     111
     112
     113/* void_stack_pop():
     114 *  Removes the top element on a void_stack and returns a reference to it.
     115 *
     116 * Arguments:
     117 *  stack -- the void_stack to pop
     118 *
     119 * Returns:
     120 *  a pointer to the popped stack element, or NULL if no elements exist on
     121 *  the stack.
     122 */
    48123void* void_stack_pop(void_stack* stack);
     124
     125
     126/* void_stack_push():
     127 *  Puts a new element on the top of a void_stack.
     128 *
     129 * Arguments:
     130 *  stack -- the void_stack being modified.
     131 *
     132 *  e     -- the element to be added
     133 *
     134 * Returns:
     135 *  true if the element was successfully added, false otherwise.
     136 */
    49137bool void_stack_push(void_stack* stack, void* e);
    50 const void* void_stack_cur(void_stack* stack);
    51 void_stack_iterator* void_stack_iterator_new(void_stack* stack);
     138
     139
     140/* void_stack_cur():
     141 *  Returns a pointer to the current element on the top of the stack.
     142 *
     143 * Arguments:
     144 *  stack -- the void_stack being queried.
     145 *
     146 * Returns:
     147 *  a pointer to the current element on the top of the stack, or NULL if no
     148 *  elements exist in the stack.
     149 */
     150const void* void_stack_cur(const void_stack* stack);
     151
     152
     153/* void_stack_iterator_new():
     154 *  Creates a new iterator for the specified void_stack.
     155 *
     156 * Arguments:
     157 *  stack -- the void_stack to be referenced by the new iterator
     158 *
     159 * Returns:
     160 *  a new void_stack_iterator, or NULL if an error occurred.
     161 */
     162void_stack_iterator* void_stack_iterator_new(const void_stack* stack);
     163
     164
     165/* void_stack_iterator_free():
     166 *  Frees a void_stack_iterator.  Does not affect the void_stack referenced
     167 *  by the iterator.
     168 *
     169 * Arguments:
     170 *  iter -- the void_stack_iterator to be free()d.
     171 */
    52172void void_stack_iterator_free(void_stack_iterator* iter);
     173
     174
     175/* void_stack_iterator_next():
     176 *  Returns a pointer to the the next element in the stack.  Iterates over
     177 *  elements starting in order from the oldest element (bottom of the stack).
     178 *
     179 * Arguments:
     180 *  iter -- the void_stack_iterator used to lookup the next element.
     181 *
     182 * Returns:
     183 *  a pointer to the next element.
     184 */
    53185const void* void_stack_iterator_next(void_stack_iterator* iter);
    54186
     187
     188/* XXX: for completeness, might want to add a void_stack_iterator_first()
     189 *      function, to return iterator to first element
     190 */
    55191#endif
Note: See TracChangeset for help on using the changeset viewer.