xref: /openbsd/gnu/usr.bin/binutils/gdb/dictionary.h (revision b725ae77)
1 /* Routines for name->symbol lookups in GDB.
2 
3    Copyright 2003 Free Software Foundation, Inc.
4 
5    Contributed by David Carlton <carlton@bactrian.org> and by Kealia,
6    Inc.
7 
8    This file is part of GDB.
9 
10    This program is free software; you can redistribute it and/or modify
11    it under the terms of the GNU General Public License as published by
12    the Free Software Foundation; either version 2 of the License, or (at
13    your option) any later version.
14 
15    This program is distributed in the hope that it will be useful, but
16    WITHOUT ANY WARRANTY; without even the implied warranty of
17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18    General Public License for more details.
19 
20    You should have received a copy of the GNU General Public License
21    along with this program; if not, write to the Free Software
22    Foundation, Inc., 59 Temple Place - Suite 330,
23    Boston, MA 02111-1307, USA.  */
24 
25 #ifndef DICTIONARY_H
26 #define DICTIONARY_H
27 
28 /* An opaque type for dictionaries; only dictionary.c should know
29    about its innards.  */
30 
31 struct dictionary;
32 
33 /* Other types needed for declarations.  */
34 
35 struct symbol;
36 struct obstack;
37 struct pending;
38 
39 
40 /* The creation functions for various implementations of
41    dictionaries.  */
42 
43 /* Create a dictionary implemented via a fixed-size hashtable.  All
44    memory it uses is allocated on OBSTACK; the environment is
45    initialized from SYMBOL_LIST.  */
46 
47 extern struct dictionary *dict_create_hashed (struct obstack *obstack,
48 					      const struct pending
49 					      *symbol_list);
50 
51 /* Create a dictionary implemented via a hashtable that grows as
52    necessary.  The dictionary is initially empty; to add symbols to
53    it, call dict_add_symbol().  Call dict_free() when you're done with
54    it.  */
55 
56 extern struct dictionary *dict_create_hashed_expandable (void);
57 
58 /* Create a dictionary implemented via a fixed-size array.  All memory
59    it uses is allocated on OBSTACK; the environment is initialized
60    from the SYMBOL_LIST.  The symbols are ordered in the same order
61    that they're found in SYMBOL_LIST.  */
62 
63 extern struct dictionary *dict_create_linear (struct obstack *obstack,
64 					      const struct pending
65 					      *symbol_list);
66 
67 /* Create a dictionary implemented via an array that grows as
68    necessary.  The dictionary is initially empty; to add symbols to
69    it, call dict_add_symbol().  Call dict_free() when you're done with
70    it.  */
71 
72 extern struct dictionary *dict_create_linear_expandable (void);
73 
74 
75 /* The functions providing the interface to dictionaries.  Note that
76    the most common parts of the interface, namely symbol lookup, are
77    only provided via iterator functions.  */
78 
79 /* Free the memory used by a dictionary that's not on an obstack.  (If
80    any.)  */
81 
82 extern void dict_free (struct dictionary *dict);
83 
84 /* Add a symbol to an expandable dictionary.  */
85 
86 extern void dict_add_symbol (struct dictionary *dict, struct symbol *sym);
87 
88 /* Is the dictionary empty?  */
89 
90 extern int dict_empty (struct dictionary *dict);
91 
92 /* A type containing data that is used when iterating over all symbols
93    in a dictionary.  Don't ever look at its innards; this type would
94    be opaque if we didn't need to be able to allocate it on the
95    stack.  */
96 
97 struct dict_iterator
98 {
99   /* The dictionary that this iterator is associated to.  */
100   const struct dictionary *dict;
101   /* The next two members are data that is used in a way that depends
102      on DICT's implementation type.  */
103   int index;
104   struct symbol *current;
105 };
106 
107 /* Initialize ITERATOR to point at the first symbol in DICT, and
108    return that first symbol, or NULL if DICT is empty.  */
109 
110 extern struct symbol *dict_iterator_first (const struct dictionary *dict,
111 					   struct dict_iterator *iterator);
112 
113 /* Advance ITERATOR, and return the next symbol, or NULL if there are
114    no more symbols.  Don't call this if you've previously received
115    NULL from dict_iterator_first or dict_iterator_next on this
116    iteration.  */
117 
118 extern struct symbol *dict_iterator_next (struct dict_iterator *iterator);
119 
120 /* Initialize ITERATOR to point at the first symbol in DICT whose
121    SYMBOL_BEST_NAME is NAME (as tested using strcmp_iw), and return
122    that first symbol, or NULL if there are no such symbols.  */
123 
124 extern struct symbol *dict_iter_name_first (const struct dictionary *dict,
125 					    const char *name,
126 					    struct dict_iterator *iterator);
127 
128 /* Advance ITERATOR to point at the next symbol in DICT whose
129    SYMBOL_BEST_NAME is NAME (as tested using strcmp_iw), or NULL if
130    there are no more such symbols.  Don't call this if you've
131    previously received NULL from dict_iterator_first or
132    dict_iterator_next on this iteration.  And don't call it unless
133    ITERATOR was created by a previous call to dict_iter_name_first
134    with the same NAME.  */
135 
136 extern struct symbol *dict_iter_name_next (const char *name,
137 					   struct dict_iterator *iterator);
138 
139 /* Return some notion of the size of the dictionary: the number of
140    symbols if we have that, the number of hash buckets otherwise.  */
141 
142 extern int dict_size (const struct dictionary *dict);
143 
144 /* Macro to loop through all symbols in a dictionary DICT, in no
145    particular order.  ITER is a struct dict_iterator (NOTE: __not__ a
146    struct dict_iterator *), and SYM points to the current symbol.
147 
148    It's implemented as a single loop, so you can terminate the loop
149    early by a break if you desire.  */
150 
151 #define ALL_DICT_SYMBOLS(dict, iter, sym)			\
152 	for ((sym) = dict_iterator_first ((dict), &(iter));	\
153 	     (sym);						\
154 	     (sym) = dict_iterator_next (&(iter)))
155 
156 #endif /* DICTIONARY_H */
157