/[ascend]/trunk/base/generic/general/stack.h
ViewVC logotype

Contents of /trunk/base/generic/general/stack.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 59 - (show annotations) (download) (as text)
Sun Oct 30 01:38:20 2005 UTC (18 years, 6 months ago) by jds
File MIME type: text/x-chdr
File size: 7028 byte(s)
- prototype unit test suite based on CUnit added.
- unit tests for base/generic/general and base/generic/utilites added.
- 2nd manual rework of doxygen documentation in general and utilities.
- bug fixes (mostly general & utilities) found during test development.
- added asc_assert prototype to redirect failures to Asc_Panic() and enable decoupling assertions from NDEBUG.
- some modifications of interface & implementation to facilitate testing.
- utilities/ascPrint & utilities/ascMalloc functions now always included in base libs to minimize recompilation when an interface chooses different options.
1 /*
2 * Stack Module
3 * by Kirk A. Abbott
4 * Created December 18, 1994.
5 * Version: $Revision: 1.2 $
6 * Version control file: $RCSfile: stack.h,v $
7 * Date last modified: $Date: 1998/06/16 15:47:44 $
8 * Last modified by: $Author: mthomas $
9 *
10 * This file is part of the Ascend Language Interpreter.
11 *
12 * Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
13 * Copyright (C) 1994 Kirk Andre Abbott
14 *
15 * The Ascend Language Interpreter is free software; you can
16 * redistribute it and/or modify it under the terms of the GNU
17 * General Public License as published by the Free Software
18 * Foundation; either version 2 of the License, or (at your option)
19 * any later version.
20 *
21 * The Ascend Language Interpreter is distributed in hope that it
22 * will be useful, but WITHOUT ANY WARRANTY; without even the implied
23 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
24 * See the GNU General Public License for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with the program; if not, write to the Free Software
28 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check
29 * the file named COPYING.
30 */
31
32 /** @file
33 * Stack Module.
34 *
35 * Stacks are occasionally used in the implementation of a compiler
36 * and/or interpreter. This module (in the spirit of the list module)
37 * attempts to provide a generic stack implementation, based on a
38 * contiquous but expandable representation.
39 * It is much like gl_list, except that push and pop are defined
40 * and much of the list fanciness is eliminated.
41 * <pre>
42 * Requires:
43 * #include "utilities/ascConfig.h"
44 * #include "compiler/compiler.h"
45 * </pre>
46 */
47
48 #ifndef __stack_h_seen__
49 #define __stack_h_seen__
50
51 /** Stack data structure. */
52 struct gs_stack_t {
53 VOIDPTR *data; /**< The data. */
54 unsigned long size; /**< Number of items used. */
55 unsigned long capacity; /**< Capacity of the stack. */
56 };
57
58 extern struct gs_stack_t *gs_stack_create(unsigned long capacity);
59 /**<
60 * Creates a new empty stack having the specified initial capacity.
61 * If the number of stack items later exceeds this size, the
62 * capacity will be expanded. It is not crucial, but a good
63 * guess will increase the performance of this module. There
64 * is an implementation-defined minimum stack size, so the actual
65 * initial capacity can be larger than the requested capacity.<br><br>
66 *
67 * Destruction of the returned stack is the responsibility of the
68 * caller. Use gs_destroy() to do this.
69 *
70 * @param capacity The desired initial stack capacity.
71 * @return Returns a pointer to the new empty gs_stack_t.
72 */
73
74 extern void gs_stack_clear(struct gs_stack_t *stack);
75 /**<
76 * Resets the stack to a *clean* state as if it had just been created.
77 * The stack will retain whatever capacity it had. The items in the
78 * stack are NOT deallocated. The specified stack may not be NULL
79 * (checked by assertion).<br><br>
80 *
81 * @param stack The stack to clear (non-NULL).
82 */
83
84 extern void gs_stack_destroy(struct gs_stack_t *stack, int dispose);
85 /**<
86 * Destroys a stack with optional deallocation of the stack items.
87 * The specified stack will be destroyed (its memory is returned to
88 * free memory). If dispose is non-zero, the items in the stack will
89 * be deallocated. This is appropriate when the stack is considered
90 * to be storing pointers to data it owns. Otherwise, dispose should
91 * be zero and the data pointers will not be deallocated. In this
92 * case the stored pointers are no longer available after calling this
93 * function, so copies of the pointers must exist somewhere to
94 * allow deallocation of the data. The specified stack can be NULL.<br><br>
95 *
96 * @param stack A pointer to the gs_stack_t to destroy.
97 * @param dispose Non-zero for deallocation of stack data items,
98 * 0 to have the data preserved.
99 */
100
101 extern void gs_stack_push(struct gs_stack_t *stack, VOIDPTR ptr);
102 /**<
103 * Pushes the specified ptr onto the stack. The stack capacity will
104 * be expanded if necessary. One can push any pointer (including NULL)
105 * onto the stack by casting appropriately. The specified stack may
106 * not be NULL (checked by assertion).<br><br>
107 *
108 * Example: <pre>
109 * struct data_t *item;
110 * struct gs_stack_t = gs_create(100L);
111 * item = (struct data_t)malloc(sizeof(struct data_t));
112 * * ....... various operations on item ........
113 * gs_stack_push(stack,(VOIDPTR)item); </pre>
114 *
115 * @see gs_stack_pop().
116 * @param stack A pointer to the gs_stack_t to modify (non-NULL).
117 * @param ptr Pointer to push onto stack.
118 */
119
120 extern VOIDPTR gs_stack_pop(struct gs_stack_t *stack);
121 /**<
122 * Pops and returns the top most item from the stack. The stack
123 * size will be appropriately accounted for. The return value is a
124 * (void *), so will need to be cast to the appropriate type before
125 * use. If the stack is empty when this function is called, NULL
126 * will be returned. The specified stack may not be NULL (checked
127 * by assertion).
128 * <pre>
129 * Example:
130 * struct data_t *item, *result;
131 * struct gs_stack_t = gs_create(100L);
132 * item = (struct data_t)malloc(sizeof(struct data_t));
133 * * ....... various operations on item ........
134 *
135 * gs_stack_push(stack,(VOIDPTR)item);
136 * result = (struct data_t*)gs_stack_pop(stack); </pre>
137 *
138 * @see gs_stack_push().
139 * @param stack A pointer to the gs_stack_t to modify (non-NULL).
140 * @return Returns the top-most data pointer as a (void *).
141 */
142
143 extern unsigned long gs_stack_size(CONST struct gs_stack_t *stack);
144 /**<
145 * Returns the current size of the stack.
146 * Zero is a valid size, meaning that the stack is empty. The
147 * specified stack may not be NULL (checked by assertion).
148 *
149 * @param stack A pointer to the gs_stack_t to query (non-NULL).
150 * @return Returns the number of data items on the stack.
151 */
152
153 extern int gs_stack_empty(CONST struct gs_stack_t *stack);
154 /**<
155 * Indicates whether the stack contains any data items.
156 * Returns TRUE (i.e. a nonzero), if the stack is empty,
157 * FALSE (zero) otherwise. The specified stack may not
158 * be NULL (checked by assertion).
159 *
160 * @param stack A pointer to the gs_stack_t to query (non-NULL).
161 * @return Returns non-zero if the stack is empty, 0 otherwise.
162 */
163
164 extern void gs_stack_apply(struct gs_stack_t *stack, void (*func) (VOIDPTR));
165 /**<
166 * Executes the function func on all the members of the stack.
167 * It will always execute the function on the items from the bottom
168 * of the stack (first-in) to the top (last-in). The function
169 * should handle NULL pointers as input gracefully. Neither the
170 * specified stack nor the func may be NULL (checked by assertion).
171 *
172 * @param stack The stack to apply func to (non-NULL).
173 * @param func The function to execute for each stack item.
174 */
175
176 #endif /* __stack_h_seen__ */
177

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22