source: trunk/include/void_stack.h @ 216

Last change on this file since 216 was 201, checked in by tim, 14 years ago

changed symbol visibility to hidden by default and explicitly exported API functions

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