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

Annotation of /trunk/base/generic/general/table.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 869 - (hide annotations) (download) (as text)
Wed Oct 4 14:03:46 2006 UTC (15 years, 10 months ago) by johnpye
File MIME type: text/x-chdr
File size: 9327 byte(s)
'hello world' works from external python module, correctly hooks into 'browser' object.
1 johnpye 869 /* ASCEND modelling environment
2     Copyright (C) 2006 Carnegie Mellon University
3     Copyright (C) 1994 Kirk Andre Abbott
4 jds 54
5 johnpye 869 This program is free software; you can redistribute it and/or modify
6     it under the terms of the GNU General Public License as published by
7     the Free Software Foundation; either version 2, or (at your option)
8     any later version.
9 aw0a 1
10 johnpye 869 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 aw0a 1
15 johnpye 869 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., 59 Temple Place - Suite 330,
18     Boston, MA 02111-1307, USA.
19     *//** @file
20     Hash Table Module.
21    
22     Many hash tables are used throughout the implementation of a compiler
23     and/or interpreter. This module (in the spirit of the list module)
24     attempts to provide a generic table implementation, based on the classic
25     *bucket and chains* for resolving collisions. Nothing fancy is done,
26     except that we cache a ptr to the last thing found, so that access to
27     it if required is fast. We append the new element to the front of the
28     chain. The hashpjw algorithm is used.
29    
30     This module is appropriate for hash tables keyed with arbitrary strings.
31     It is not appropriate for use with symbol table entry keys.
32    
33     Requires:
34     #include "utilities/ascConfig.h"
35     *//*
36     by Kirk A. Abbott
37     Created December 29, 1994.
38     Last in CVS $Revision: 1.3 $ $Date: 1998/06/16 15:47:47 $ $Author: mthomas $
39     */
40    
41     #ifndef ASC_TABLE_H
42     #define ASC_TABLE_H
43    
44 aw0a 1 typedef void (*TableIteratorOne)(void *);
45 jds 59 /**<
46 jds 54 * Typedef for casting of 1-parameter functions
47 jds 59 * being passed to TableApply* functions.
48 jds 54 */
49 aw0a 1 typedef void (*TableIteratorTwo)(void *,void *);
50 jds 59 /**<
51 jds 54 * Typedef for casting of 2-parameter functions
52 jds 59 * being passed to TableApply* functions.
53 aw0a 1 */
54    
55 johnpye 593 ASC_DLLSPEC(struct Table *) CreateTable(unsigned long hashsize);
56 jds 54 /**<
57 jds 59 * Creates a new hash table with the specified hashsize.
58     * This ideally should be a prime number. A good choice will give
59     * better performance without wasting too much memory. Some good
60     * prime numbers are: 31, 97, 113, 229, 541, 1023, 3571.
61     * Everything is appropriately initialized.<br><br>
62     *
63     * The function returns a pointer to the newly created hash table.
64     * Deallocation of the table is the responsibility of the caller
65     * using DestroyTable().
66     *
67     * @param hashsize The number of buckets in the new hash table.
68     * @return A pointer to the new hash table.
69     * @todo Should general/table:CreateTable have lower limit on hashsize?
70 aw0a 1 */
71    
72 johnpye 593 ASC_DLLSPEC(void ) DestroyTable(struct Table *table, int dispose);
73 jds 54 /**<
74 jds 59 * Destroys the given table. If dispose is set to TRUE (nonzero),
75     * the data items stored in the table will be deallocated as well.
76     * Do not refer to a table after it has been destroyed. The
77     * specified table may be NULL, in which case this function has no
78     * effect.
79 aw0a 1 *
80 jds 59 * @param table Pointer to the hash table to destroy (non-NULL).
81     * @param dispose If non-zero deallocate the stored data also,
82     * if 0 the data is destroyed as well.
83 aw0a 1 */
84    
85 johnpye 593 ASC_DLLSPEC(void ) AddTableData(struct Table * table, void *data, CONST char *id);
86 jds 54 /**<
87 jds 59 * Stores *data* in the hash table using id as the lookup key.
88     * Currently id must be a unique NULL-terminated string. In the
89     * future, this may be changed to a generic lookup function
90     * supplied by the user. If the id is not unique in the table,
91     * the data is not added. The *data* can be anything, including
92     * a NULL pointer. A pointer to the last item added is cached so
93     * that subsequent lookup is fairly fast (see TableLastFind()).
94     * Neither table nor id may be NULL (checked by assertion).
95     *
96     * @param table Pointer to the hash table to add to (non-NULL).
97     * @param data The data to store in the table.
98     * @param id NULL-terminated string to use for lookup key (non-NULL).
99 aw0a 1 */
100    
101 johnpye 593 ASC_DLLSPEC(void *) LookupTableData(struct Table *table, CONST char *id);
102 jds 54 /**<
103 jds 59 * Retrieves the data stored in the table under the key *id*.
104     * It will return NULL if id is not found. A pointer to the last item
105     * looked up is cached so that subsequent lookup is fairly fast
106     * (see TableLastFind()). The return value will generally need to be
107     * cast to the correct type. Neither table nor id may be NULL
108     * (checked by assertion).
109     *
110     * @param table Pointer to the hash table to query (non-NULL).
111     * @param id NULL-terminated string to use for lookup key (non-NULL).
112     * @return The data stored under lookup key id, or NULL if not found.
113 aw0a 1 */
114    
115 johnpye 593 ASC_DLLSPEC(void *) RemoveTableData(struct Table *table, char *id);
116 jds 54 /**<
117 jds 59 * Removes the data stored in the table under the key *id*.
118     * It will return NULL if id is not found. Otherwise, it will
119     * return the data that was stored under id. The data is not
120     * deallocated. The return value will generally need to be
121     * cast to the correct type. Neither table nor id may be NULL
122     * (checked by assertion).
123     *
124     * @param table Pointer to the hash table to query (non-NULL).
125     * @param id NULL-terminated string to use for lookup key (non-NULL).
126     * @return The data stored under lookup key id, or NULL if not found.
127 aw0a 1 */
128    
129 johnpye 593 ASC_DLLSPEC(void ) TableApplyOne(struct Table *table,
130 jds 54 TableIteratorOne applyfunc,
131     char *id);
132     /**<
133 jds 59 * Calls the specified function, passing the data stored in the table
134     * under key *id* as argument. The lookup is fast if the data item was
135     * the last searched for, slower otherwise. The function applyfunc must
136     * be able to handle NULL pointers gracefully. Neither table, applyfunc,
137     * nor id may be NULL (checked by assertion).
138     *
139     * @param table Pointer to the hash table to use (non-NULL).
140     * @param applyfunc Pointer to the function to apply (non-NULL).
141     * @param id NULL-terminated string to use for lookup key (non-NULL).
142 aw0a 1 */
143    
144 johnpye 593 ASC_DLLSPEC(void ) TableApplyAll(struct Table *table, TableIteratorOne applyfunc);
145 jds 54 /**<
146 jds 59 * Calls the specified function for each data item stored in the table.
147     * The order of operation dependends on internal table structure, so is
148     * not predictable and should not be relied upon. Using this function
149     * should be a lot faster than fetching each element independently and
150     * applying applyfunc to it. The function must be able to handle NULL
151     * pointers gracefully. Neither table nor applyfunc may be NULL
152     * (checked by assertion).
153     *
154     * @param table Pointer to the hash table to use (non-NULL).
155     * @param applyfunc Pointer to the function to apply (non-NULL).
156 aw0a 1 */
157    
158 johnpye 593 ASC_DLLSPEC(void ) TableApplyAllTwo(struct Table *table,
159 jds 54 TableIteratorTwo applyfunc,
160     void *arg2);
161     /**<
162 jds 59 * Calls the specified function for each data item stored in the table.
163     * This is the same as TableApplyAll(), except that arg2 is passed as a
164     * second argument to applyfunc allowing a closure. The order of
165     * operation dependends on internal table structure, so is not
166     * predictable and should not be relied upon. Using this function
167     * should be a lot faster than fetching each element independently and
168     * applying applyfunc to it. The function must be able to handle NULL
169     * pointers gracefully. Neither table nor applyfunc may be NULL
170     * (checked by assertion).
171     *
172     * @param table Pointer to the hash table to use (non-NULL).
173     * @param applyfunc Pointer to the function to apply (non-NULL).
174     * @param arg2 The 2nd argument to pass to applyfunc.
175 aw0a 1 */
176    
177 jds 59 extern void PrintTable(FILE *file, struct Table *table);
178 jds 54 /**<
179 jds 59 * Prints information about the table to the given file. This
180     * information currently includes an ordered list of bucket
181     * numbers and id strings for each data item in the table.
182     * The file must be opened and ready for writing. Neither table
183     * nor file may be NULL (checked by assertion).
184     *
185     * @param file Open, writable file stream to receive the report (non-NULL).
186     * @param table Pointer to the hash table to query (non-NULL).
187 aw0a 1 */
188    
189 johnpye 593 ASC_DLLSPEC(unsigned long ) TableSize(struct Table *table);
190 jds 54 /**<
191 jds 59 * Returns the current number of entries in the table. The
192     * specified table may not be NULL (checked by assertion).
193     *
194     * @param table Pointer to the hash table to query (non-NULL).
195 aw0a 1 */
196    
197 johnpye 593 ASC_DLLSPEC(unsigned long ) TableHashSize(struct Table *table);
198 jds 54 /**<
199 jds 59 * Returns the current hashsize of the table. If internally we
200     * change the hashing/collision algorithm, this may be useful
201     * information to someone. At the moment it is the size
202     * requested and hence is not very useful. The specified table
203     * may not be NULL (checked by assertion).
204     *
205     * @param table Pointer to the hash table to query (non-NULL).
206 aw0a 1 */
207    
208 johnpye 593 ASC_DLLSPEC(void *) TableLastFind(struct Table *table);
209 jds 54 /**<
210 jds 59 * Returns the data item that was last added to or retrieved from the
211     * table. Could be useful for those, "do you exist?; now do something
212     * with you" situations. Returns NULL if no item was added or retrieved
213     * from the table. The specified table may not be NULL (checked by
214     * assertion).
215     *
216     * @param table Pointer to the hash table to query (non-NULL).
217 aw0a 1 */
218    
219 johnpye 869 #endif /* ASC_TABLE_H */

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