Merge branch 'release-2.140.101'
[feisty_meow.git] / nucleus / library / structures / symbol_table.h
1 #ifndef SYMBOL_TABLE_CLASS
2 #define SYMBOL_TABLE_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : symbol_table                                                      *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 1991-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include "pointer_hash.h"
19 #include "string_hash.h"
20 #include "symbol_table.h"
21
22 #include <basis/astring.h>
23 #include <basis/functions.h>
24 #include <basis/guards.h>
25
26 namespace structures {
27
28 template <class contents> class internal_symbol_indexer;
29 template <class contents> class internal_symbol_info;
30 template <class contents> class internal_symbol_list;
31
32 //! Maintains a list of names, where each name has a type and some contents.
33
34 template <class contents>
35 class symbol_table
36 {
37 public:
38   //! constructs a symbol table with sufficient size for "estimated_elements".
39   /*! the "estimated_elements" dictates how large the symbol table's key space is.  the
40   number of keys that can be stored without collisions (assuming perfect distribution
41   from the hash function) will be close to the number of elements specified. */
42   symbol_table(int estimated_elements = 100);
43
44   symbol_table(const symbol_table<contents> &to_copy);
45
46   ~symbol_table();
47
48   int symbols() const;
49     //!< returns the number of symbols listed in the table.
50
51   int estimated_elements() const;
52     //!< returns the number of symbols the table is optimized for.
53
54   void rehash(int estimated_elements);
55     //!< resizes underlying table to support "estimated_elements".
56
57   void hash_appropriately(int estimated_elements);
58     //!< Resizes the number of table slots to have space for "estimated_elements".
59
60   symbol_table &operator =(const symbol_table<contents> &to_copy);
61
62   basis::outcome add(const basis::astring &name, const contents &storage);
63     //!< Enters a symbol name into the table along with some contents.
64     /*!< If the name already exists in the table, then the previous contents
65     are replaced with these, but EXISTING is returned.  If this is a new entry,
66     then IS_NEW is returned instead. */
67
68   const basis::astring &name(int index) const;
69     //!< returns the name held at the "index".
70     /*!< if the index is invalid, then a bogus name is returned. */
71
72   void names(string_set &to_fill) const;
73     //!< returns the names of all the symbols currently held.
74
75   contents &operator [] (int index);
76     //!< provides access to the symbol_table's contents at the "index".
77   const contents &operator [] (int index) const;
78     //!< provides a constant peek at the contents at the "index".
79
80   const contents &get(int index) const { return operator[](index); }
81     //!< named equivalent for the bracket operator.
82   contents &use(int index) { return operator[](index); }
83     //!< named equivalent for the bracket operator.
84
85   contents *find(const basis::astring &name) const;
86     //!< returns the contents held for "name" or NULL_POINTER if it wasn't found.
87
88   contents *find(const basis::astring &name,
89           basis::string_comparator_function *comparator) const;
90     //!< Specialized search via a comparison method "comparator".
91     /*!< Searches for a symbol by its "name" but uses a special comparison
92     function "comparator" to determine if the name is really equal.  This
93     method is by its nature slower than the main find method, since all buckets
94     must be searched until a match is found.  It is just intended to provide
95     extensibility. */
96
97   int dep_find(const basis::astring &name) const;
98     //!< Searches for a symbol by its "name".
99     /*!< Returns the index or NOT_FOUND.  NOTE: this is deprecated; it is far
100     faster to use the first find method above. */
101
102   //! Locates the symbol at position "index" and stores it to the parameters.
103   /*! retrieve() accesses the "index"th symbol in the table and returns the
104       held contents for it as well as its name.  if the outcome is OKAY, then
105       the returned information is valid.  otherwise, the search failed. */
106   basis::outcome retrieve(int index, basis::astring &symbol_name, contents &contains) const;
107
108   basis::outcome whack(const basis::astring &name);
109     //!< removes a symbol from the table.
110     /*!< this succeeds only if the symbol name is present in the table. */
111
112   basis::outcome zap_index(int index);
113     //!< zaps the entry at the specified index.  slower than whack().
114
115   void reset();  //<! removes all symbols from the table.
116
117 private:
118   internal_symbol_list<contents> *_symbol_list;  //!< our table of symbols.
119   internal_symbol_indexer<contents> *_tracker;  //!< indexed lookup support.
120
121   internal_symbol_info<contents> *get_index(int index) const;
122     //!< returns the info item at "index" or NULL_POINTER.
123 };
124
125 //////////////
126
127 template <class contents>
128 bool symbol_table_compare(const symbol_table<contents> &a,
129     const symbol_table<contents> &b);
130   //!< returns true if table "a" and table "b" have the same contents.
131
132 //////////////
133
134 // implementations below...
135
136 //#define DEBUG_SYMBOL_TABLE
137   // uncomment for noisier debugging.
138
139 #ifdef DEBUG_SYMBOL_TABLE
140   #undef LOG
141   #define LOG(s) CLASS_EMERGENCY_LOG(program_wide_logger::get(), s)
142 #endif
143
144 //////////////
145
146 // this structure keeps track of our symbol table elements.
147
148 template <class contents>
149 class internal_symbol_info
150 {
151 public:
152   contents _content;  // the object provided by the user.
153   basis::astring _name;  // symbol's name.
154
155   internal_symbol_info(const contents &content, const basis::astring &name)
156   : _content(content), _name(name) {}
157 };
158
159 //////////////
160
161 // this is our tracking system that allows us to offer array like services.
162 // each symbol held has an address as one of our wrappers.  thus we can
163 // list those addresses in a hash table along with listing the contents
164 // in the main hash table.  the pointer_hash gives us a list of ids set, so
165 // we can have some ordering for the items in the table.
166
167 template <class contents>
168 class internal_pointer_hider
169 {
170 public:
171   internal_symbol_info<contents> *_held;
172
173   internal_pointer_hider(internal_symbol_info<contents> *held) : _held(held) {}
174 };
175
176 template <class contents>
177 class internal_symbol_indexer
178 : public pointer_hash<internal_pointer_hider<contents> >
179 {
180 public:
181   internal_symbol_indexer(int elems)
182       : pointer_hash<internal_pointer_hider<contents> >(elems) {}
183 };
184
185 //////////////
186
187 // this object maintains the symbol table's contents.
188
189 template <class contents>
190 class internal_symbol_list
191 : public string_hash<internal_symbol_info<contents> >
192 {
193 public:
194   internal_symbol_list(int elems)
195       : string_hash<internal_symbol_info<contents> >(elems) {}
196 };
197
198 //////////////
199
200 // the main algorithms class implementing the external interface.
201
202 #undef static_class_name
203 #define static_class_name() "symbol_table"
204
205 template <class contents>
206 symbol_table<contents>::symbol_table(int estimated_elements)
207 : _symbol_list(new internal_symbol_list<contents>(estimated_elements)),
208   _tracker(new internal_symbol_indexer<contents>(estimated_elements))
209 {}
210
211 template <class contents>
212 symbol_table<contents>::symbol_table(const symbol_table<contents> &to_copy)
213 : _symbol_list(new internal_symbol_list<contents>
214       (to_copy._symbol_list->estimated_elements())),
215   _tracker(new internal_symbol_indexer<contents>(to_copy.estimated_elements()))
216 { *this = to_copy; }
217
218 template <class contents>
219 symbol_table<contents>::~symbol_table()
220 {
221   WHACK(_symbol_list);
222   WHACK(_tracker);
223 }
224
225 template <class contents>
226 int symbol_table<contents>::estimated_elements() const
227 { return _symbol_list->estimated_elements(); }
228
229 template <class contents>
230 void symbol_table<contents>::rehash(int estimated_elements)
231 {
232   _symbol_list->rehash(estimated_elements);
233   _tracker->rehash(estimated_elements);
234 }
235
236 template <class contents>
237 void symbol_table<contents>::hash_appropriately(int new_elements)
238 { rehash(new_elements); }
239
240 template <class contents>
241 int symbol_table<contents>::symbols() const
242 { return _tracker->ids().elements(); }
243
244 template <class contents>
245 symbol_table<contents> &symbol_table<contents>::
246     operator =(const symbol_table &to_copy)
247 {
248   if (this == &to_copy) return *this;
249   reset();
250   for (int i = 0; i < to_copy.symbols(); i++) {
251     internal_symbol_info<contents> *info = to_copy.get_index(i);
252     if (info) {
253       internal_symbol_info<contents> *new_info
254           = new internal_symbol_info<contents>(*info);
255       _symbol_list->add(info->_name, new_info);
256       internal_pointer_hider<contents> *new_track = 
257           new internal_pointer_hider<contents>(new_info);
258       _tracker->add(new_info, new_track);
259     }
260   }
261   return *this;
262 }
263
264 template <class contents>
265 void symbol_table<contents>::reset()
266 {
267   _symbol_list->reset();
268   _tracker->reset();
269 }
270
271 template <class contents>
272 const basis::astring &symbol_table<contents>::name(int index) const
273 {
274   bounds_return(index, 0, symbols() - 1, basis::bogonic<basis::astring>());
275   return get_index(index)->_name;
276 }
277
278 template <class contents>
279 void symbol_table<contents>::names(string_set &to_fill) const
280 {
281   to_fill.reset();
282   for (int i = 0; i < symbols(); i++)
283     to_fill += get_index(i)->_name;
284 }
285
286 template <class contents>
287 internal_symbol_info<contents> *symbol_table<contents>::
288     get_index(int index) const
289 {
290   bounds_return(index, 0, symbols() - 1, NULL_POINTER);
291   return _tracker->find(_tracker->ids()[index])->_held;
292 }
293
294 template <class contents>
295 const contents &symbol_table<contents>::operator [] (int index) const
296 {
297   bounds_return(index, 0, symbols() - 1, basis::bogonic<contents>());
298   internal_symbol_info<contents> *found = get_index(index);
299   if (!found) return basis::bogonic<contents>();
300   return found->_content;
301 }
302
303 template <class contents>
304 contents &symbol_table<contents>::operator [] (int index)
305 {
306   bounds_return(index, 0, symbols() - 1, basis::bogonic<contents>());
307   internal_symbol_info<contents> *found = get_index(index);
308   if (!found) return basis::bogonic<contents>();
309   return found->_content;
310 }
311
312 template <class contents>
313 contents *symbol_table<contents>::find(const basis::astring &name) const
314
315 //  FUNCDEF("find [name]");
316   internal_symbol_info<contents> *found = _symbol_list->find(name);
317   if (!found) return NULL_POINTER;
318   return &found->_content;
319 }
320
321 template <class contents>
322 int symbol_table<contents>::dep_find(const basis::astring &name) const
323 {
324   internal_symbol_info<contents> *entry = _symbol_list->find(name);
325   if (!entry) return basis::common::NOT_FOUND;
326
327   for (int i = 0; i < symbols(); i++) {
328     if (_tracker->ids()[i] == entry) return i;
329   }
330   return basis::common::NOT_FOUND;  // this is bad; it should have been found.
331 }
332
333 template <class contents>
334 struct sym_tab_apply_data
335 {
336   basis::string_comparator_function *_scf;
337   contents *_found;
338   basis::astring _to_find;
339
340   sym_tab_apply_data() : _scf(NULL_POINTER), _found(NULL_POINTER) {}
341 };
342
343 template <class contents>
344 bool sym_tab_finder_apply(const basis::astring &key, contents &current,
345     void *data_link)
346 {
347 #ifdef DEBUG_SYMBOL_TABLE
348   FUNCDEF("sym_tab_finder_apply");
349 #endif
350   sym_tab_apply_data<contents> *package
351       = (sym_tab_apply_data<contents> *)data_link;
352 #ifdef DEBUG_SYMBOL_TABLE
353   LOG(basis::astring("  checking ") + key);
354 #endif
355   bool equals = package->_scf(key, package->_to_find);
356   if (equals) {
357     package->_found = &current;
358     return false;  // done.
359   }
360   return true;  // keep going.
361 }
362
363 template <class contents>
364 contents *symbol_table<contents>::find(const basis::astring &name,
365     basis::string_comparator_function *comparator) const
366 {
367 #ifdef DEBUG_SYMBOL_TABLE
368   FUNCDEF("find [comparator]");
369 #endif
370   if (!comparator) return find(name);  // devolve to simplified call.
371 #ifdef DEBUG_SYMBOL_TABLE
372   LOG(basis::astring("looking for ") + name);
373 #endif
374   sym_tab_apply_data<contents> pack;
375   pack._to_find = name;
376   pack._scf = comparator;
377   // iterate across all the items in the hash.
378   _symbol_list->apply(sym_tab_finder_apply, &pack);
379   return pack._found;
380 }
381
382 template <class contents>
383 basis::outcome symbol_table<contents>::add(const basis::astring &name, const contents &to_add)
384 {
385 //  FUNCDEF("add");
386   internal_symbol_info<contents> *found = _symbol_list->find(name);
387   if (!found) {
388     // not there already.
389     internal_symbol_info<contents> *new_item
390         = new internal_symbol_info<contents>(to_add, name);
391     _symbol_list->add(name, new_item);
392     internal_pointer_hider<contents> *new_track = 
393         new internal_pointer_hider<contents>(new_item);
394     _tracker->add(new_item, new_track);
395     return basis::common::IS_NEW;
396   }
397   // overwrite the existing contents.
398   found->_content = to_add;
399   return basis::common::EXISTING;
400 }
401
402 template <class contents>
403 basis::outcome symbol_table<contents>::zap_index(int index)
404 {
405   basis::astring dead_name = name(index);
406   return whack(dead_name);
407 }
408
409 template <class contents>
410 basis::outcome symbol_table<contents>::whack(const basis::astring &name)
411 {
412 //  FUNCDEF("whack");
413   internal_symbol_info<contents> *sep_ind = _symbol_list->find(name);
414     // we need this pointer so we can find the tracker entry easily.
415   bool found_it = _symbol_list->zap(name);
416   if (found_it) {
417     _tracker->zap(sep_ind);
418   }
419   return found_it? basis::common::OKAY : basis::common::NOT_FOUND;
420 }
421
422 template <class contents>
423 basis::outcome symbol_table<contents>::retrieve(int index, basis::astring &name,
424     contents &got) const
425 {
426   bounds_return(index, 0, symbols() - 1, basis::common::NOT_FOUND);
427   internal_symbol_info<contents> *found = get_index(index);
428   name = found->_name;
429   got = found->_content;
430   return basis::common::OKAY;
431 }
432
433 //////////////
434
435 template <class contents>
436 bool symbol_table_compare(const symbol_table<contents> &a,
437     const symbol_table<contents> &b)
438 {
439 //  FUNCDEF("symbol_table_compare");
440
441   string_set names_a;
442   a.names(names_a);
443   string_set names_b;
444   b.names(names_b);
445   if (names_a != names_b) return false;
446
447   for (int i = 0; i < names_a.elements(); i++) {
448     const basis::astring &current_key = names_a[i];
449     const contents *a_value = a.find(current_key);
450     const contents *b_value = b.find(current_key);
451     if (!a_value || !b_value) continue;  // not good.
452     if (*a_value != *b_value) return false;
453   }
454   return true;
455 }
456
457 #ifdef DEBUG_SYMBOL_TABLE
458   #undef LOG
459 #endif
460
461 #undef static_class_name
462
463 } //namespace.
464
465 #endif
466
467