Changeset 89


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

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

Location:
trunk
Files:
2 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
  • trunk/lib/void_stack.c

    r81 r89  
    105105
    106106
    107 unsigned short void_stack_size(void_stack* stack)
     107unsigned short void_stack_size(const void_stack* stack)
    108108{
    109109  return stack->top;
     110}
     111
     112
     113void* void_stack_pop(void_stack* stack)
     114{
     115  void* ret_val = NULL;
     116
     117  if(stack->top > 0)
     118  {
     119    ret_val = stack->elements[--(stack->top)];
     120    stack->elements[stack->top] = NULL;
     121  }
     122
     123  return ret_val;
    110124}
    111125
     
    123137
    124138
    125 void* void_stack_pop(void_stack* stack)
     139const void* void_stack_cur(const void_stack* stack)
    126140{
    127141  void* ret_val = NULL;
    128142
    129143  if(stack->top > 0)
    130   {
    131     ret_val = stack->elements[--(stack->top)];
    132     stack->elements[stack->top] = NULL;
    133   }
    134   else
    135     ret_val = NULL;
     144    ret_val = stack->elements[stack->top-1];
    136145
    137146  return ret_val;
     
    139148
    140149
    141 const void* void_stack_cur(void_stack* stack)
    142 {
    143   void* ret_val = NULL;
    144 
    145   if(stack->top > 0)
    146     ret_val = stack->elements[stack->top-1];
    147   else
    148     ret_val = NULL;
    149 
    150   return ret_val;
    151 }
    152 
    153 
    154 void_stack_iterator* void_stack_iterator_new(void_stack* stack)
     150void_stack_iterator* void_stack_iterator_new(const void_stack* stack)
    155151{
    156152  void_stack_iterator* ret_val = NULL;
    157153 
    158   ret_val = (void_stack_iterator*)malloc(sizeof(void_stack_iterator));
    159   if (ret_val != NULL)
     154  if(stack != NULL)
    160155  {
    161     ret_val->stack = stack;
    162     ret_val->cur = 0;
     156    ret_val = (void_stack_iterator*)malloc(sizeof(void_stack_iterator));
     157    if (ret_val != NULL)
     158    {
     159      ret_val->stack = stack;
     160      ret_val->cur = 0;
     161    }
    163162  }
    164163
Note: See TracChangeset for help on using the changeset viewer.