[168] | 1 | /** |
---|
| 2 | * @file |
---|
| 3 | * |
---|
[150] | 4 | * Copyright (C) 2005,2007,2009 Timothy D. Morgan |
---|
[31] | 5 | * |
---|
| 6 | * This program is free software; you can redistribute it and/or modify |
---|
| 7 | * it under the terms of the GNU General Public License as published by |
---|
[111] | 8 | * the Free Software Foundation; version 3 of the License. |
---|
[31] | 9 | * |
---|
| 10 | * This program is distributed in the hope that it will be useful, |
---|
| 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
---|
| 13 | * GNU General Public License for more details. |
---|
| 14 | * |
---|
| 15 | * You should have received a copy of the GNU General Public License |
---|
| 16 | * along with this program; if not, write to the Free Software |
---|
| 17 | * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. |
---|
| 18 | * |
---|
| 19 | * $Id: void_stack.h 168 2010-03-03 00:08:42Z tim $ |
---|
| 20 | */ |
---|
| 21 | |
---|
[150] | 22 | #ifndef _VOID_STACK_H |
---|
| 23 | #define _VOID_STACK_H |
---|
| 24 | |
---|
[31] | 25 | #include <stdlib.h> |
---|
| 26 | #include <stdbool.h> |
---|
| 27 | #include <string.h> |
---|
[150] | 28 | #include "talloc.h" |
---|
[31] | 29 | |
---|
| 30 | typedef struct _void_stack |
---|
| 31 | { |
---|
| 32 | void** elements; |
---|
| 33 | unsigned short max_size; |
---|
| 34 | unsigned short top; |
---|
| 35 | } void_stack; |
---|
| 36 | |
---|
| 37 | typedef struct _void_stack_iterator |
---|
| 38 | { |
---|
[89] | 39 | const void_stack* stack; |
---|
[31] | 40 | unsigned short cur; |
---|
| 41 | } void_stack_iterator; |
---|
| 42 | |
---|
| 43 | |
---|
[89] | 44 | /* void_stack_new(): |
---|
| 45 | * Allocates a new void_stack. |
---|
| 46 | * |
---|
| 47 | * Arguments: |
---|
| 48 | * max_size -- the maxiumum number of elements |
---|
| 49 | * which may be pushed onto the stack. |
---|
| 50 | * |
---|
| 51 | * Returns: |
---|
| 52 | * a pointer to the newly allocated void_stack, or NULL if an error occurred. |
---|
| 53 | */ |
---|
[31] | 54 | void_stack* void_stack_new(unsigned short max_size); |
---|
[89] | 55 | |
---|
| 56 | |
---|
| 57 | /* void_stack_copy(): |
---|
| 58 | * Makes a shallow copy of void_stack. |
---|
| 59 | * |
---|
| 60 | * Arguments: |
---|
| 61 | * v -- the stack to make a copy of. |
---|
| 62 | * |
---|
| 63 | * Returns: |
---|
| 64 | * a pointer to the duplicate void_stack, or NULL If an error occurred. |
---|
| 65 | */ |
---|
[38] | 66 | void_stack* void_stack_copy(const void_stack* v); |
---|
[89] | 67 | |
---|
| 68 | |
---|
| 69 | /* void_stack_copy_reverse(): |
---|
| 70 | * Makes a shallow copy of void_stack in reverse order. |
---|
| 71 | * |
---|
| 72 | * Arguments: |
---|
| 73 | * v -- the stack to make a copy of. |
---|
| 74 | * |
---|
| 75 | * Returns: |
---|
| 76 | * a pointer to the duplicate void_stack (which will be in reverse order), |
---|
| 77 | * or NULL If an error occurred. |
---|
| 78 | */ |
---|
[38] | 79 | void_stack* void_stack_copy_reverse(const void_stack* v); |
---|
[89] | 80 | |
---|
| 81 | |
---|
| 82 | /* void_stack_free(): |
---|
| 83 | * Frees the memory associated with a void_stack, but not the elements held |
---|
| 84 | * on the stack. |
---|
| 85 | * |
---|
| 86 | * Arguments: |
---|
| 87 | * stack -- the stack to be free()d. |
---|
| 88 | */ |
---|
[80] | 89 | void void_stack_free(void_stack* stack); |
---|
[89] | 90 | |
---|
| 91 | |
---|
| 92 | /* void_stack_free_deep(): |
---|
| 93 | * Frees the memory associated with a void_stack and the elements referenced |
---|
| 94 | * by the stack. Do not use this function if the elements of the stack |
---|
| 95 | * are also free()d elsewhere, or contain pointers to other memory which |
---|
| 96 | * cannot be otherwise free()d. |
---|
| 97 | * |
---|
| 98 | * Arguments: |
---|
| 99 | * stack -- the stack to be free()d. |
---|
| 100 | */ |
---|
[80] | 101 | void void_stack_free_deep(void_stack* stack); |
---|
[89] | 102 | |
---|
| 103 | |
---|
| 104 | /* void_stack_size(): |
---|
| 105 | * Query the current number of elements on a void_stack() |
---|
| 106 | * |
---|
| 107 | * Arguments: |
---|
| 108 | * stack -- the void_stack to query |
---|
| 109 | * |
---|
| 110 | * Returns: |
---|
| 111 | * the number of elements currently on the stack. |
---|
| 112 | */ |
---|
| 113 | unsigned short void_stack_size(const void_stack* stack); |
---|
| 114 | |
---|
| 115 | |
---|
| 116 | /* void_stack_pop(): |
---|
| 117 | * Removes the top element on a void_stack and returns a reference to it. |
---|
| 118 | * |
---|
| 119 | * Arguments: |
---|
| 120 | * stack -- the void_stack to pop |
---|
| 121 | * |
---|
| 122 | * Returns: |
---|
| 123 | * a pointer to the popped stack element, or NULL if no elements exist on |
---|
| 124 | * the stack. |
---|
| 125 | */ |
---|
[31] | 126 | void* void_stack_pop(void_stack* stack); |
---|
[89] | 127 | |
---|
| 128 | |
---|
| 129 | /* void_stack_push(): |
---|
| 130 | * Puts a new element on the top of a void_stack. |
---|
| 131 | * |
---|
| 132 | * Arguments: |
---|
| 133 | * stack -- the void_stack being modified. |
---|
| 134 | * |
---|
| 135 | * e -- the element to be added |
---|
| 136 | * |
---|
| 137 | * Returns: |
---|
| 138 | * true if the element was successfully added, false otherwise. |
---|
| 139 | */ |
---|
[31] | 140 | bool void_stack_push(void_stack* stack, void* e); |
---|
[89] | 141 | |
---|
| 142 | |
---|
| 143 | /* void_stack_cur(): |
---|
| 144 | * Returns a pointer to the current element on the top of the stack. |
---|
| 145 | * |
---|
| 146 | * Arguments: |
---|
| 147 | * stack -- the void_stack being queried. |
---|
| 148 | * |
---|
| 149 | * Returns: |
---|
| 150 | * a pointer to the current element on the top of the stack, or NULL if no |
---|
| 151 | * elements exist in the stack. |
---|
| 152 | */ |
---|
| 153 | const void* void_stack_cur(const void_stack* stack); |
---|
| 154 | |
---|
| 155 | |
---|
| 156 | /* void_stack_iterator_new(): |
---|
| 157 | * Creates a new iterator for the specified void_stack. |
---|
| 158 | * |
---|
| 159 | * Arguments: |
---|
| 160 | * stack -- the void_stack to be referenced by the new iterator |
---|
| 161 | * |
---|
| 162 | * Returns: |
---|
| 163 | * a new void_stack_iterator, or NULL if an error occurred. |
---|
| 164 | */ |
---|
| 165 | void_stack_iterator* void_stack_iterator_new(const void_stack* stack); |
---|
| 166 | |
---|
| 167 | |
---|
| 168 | /* void_stack_iterator_free(): |
---|
| 169 | * Frees a void_stack_iterator. Does not affect the void_stack referenced |
---|
| 170 | * by the iterator. |
---|
| 171 | * |
---|
| 172 | * Arguments: |
---|
| 173 | * iter -- the void_stack_iterator to be free()d. |
---|
| 174 | */ |
---|
[80] | 175 | void void_stack_iterator_free(void_stack_iterator* iter); |
---|
[89] | 176 | |
---|
| 177 | |
---|
| 178 | /* void_stack_iterator_next(): |
---|
| 179 | * Returns a pointer to the the next element in the stack. Iterates over |
---|
| 180 | * elements starting in order from the oldest element (bottom of the stack). |
---|
| 181 | * |
---|
| 182 | * Arguments: |
---|
| 183 | * iter -- the void_stack_iterator used to lookup the next element. |
---|
| 184 | * |
---|
| 185 | * Returns: |
---|
| 186 | * a pointer to the next element. |
---|
| 187 | */ |
---|
[33] | 188 | const void* void_stack_iterator_next(void_stack_iterator* iter); |
---|
[79] | 189 | |
---|
[89] | 190 | |
---|
| 191 | /* XXX: for completeness, might want to add a void_stack_iterator_first() |
---|
| 192 | * function, to return iterator to first element |
---|
| 193 | */ |
---|
[79] | 194 | #endif |
---|