185597Speter/* Routines for name->symbol lookups in GDB.
285597Speter
385597Speter   Copyright 2003 Free Software Foundation, Inc.
485597Speter
585597Speter   Contributed by David Carlton <carlton@bactrian.org> and by Kealia,
685597Speter   Inc.
785597Speter
885597Speter   This file is part of GDB.
985597Speter
1085597Speter   This program is free software; you can redistribute it and/or modify
1185597Speter   it under the terms of the GNU General Public License as published by
1285597Speter   the Free Software Foundation; either version 2 of the License, or (at
1385597Speter   your option) any later version.
1485597Speter
1585597Speter   This program is distributed in the hope that it will be useful, but
1685597Speter   WITHOUT ANY WARRANTY; without even the implied warranty of
1785597Speter   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1885597Speter   General Public License for more details.
1985597Speter
2085597Speter   You should have received a copy of the GNU General Public License
2185597Speter   along with this program; if not, write to the Free Software
2285597Speter   Foundation, Inc., 59 Temple Place - Suite 330,
2385597Speter   Boston, MA 02111-1307, USA.  */
2485597Speter
2585597Speter#ifndef DICTIONARY_H
2685597Speter#define DICTIONARY_H
2785597Speter
2885597Speter/* An opaque type for dictionaries; only dictionary.c should know
29216338Sdim   about its innards.  */
30216338Sdim
31216338Sdimstruct dictionary;
3285597Speter
3385597Speter/* Other types needed for declarations.  */
3485597Speter
3585597Speterstruct symbol;
3685597Speterstruct obstack;
3785597Speterstruct pending;
3885679Speter
3985679Speter
4085679Speter/* The creation functions for various implementations of
4185597Speter   dictionaries.  */
4285952Speter
4385952Speter/* Create a dictionary implemented via a fixed-size hashtable.  All
4485952Speter   memory it uses is allocated on OBSTACK; the environment is
4585679Speter   initialized from SYMBOL_LIST.  */
4685679Speter
4785952Speterextern struct dictionary *dict_create_hashed (struct obstack *obstack,
4885679Speter					      const struct pending
4985597Speter					      *symbol_list);
5085679Speter
5185679Speter/* Create a dictionary implemented via a hashtable that grows as
5285679Speter   necessary.  The dictionary is initially empty; to add symbols to
5385597Speter   it, call dict_add_symbol().  Call dict_free() when you're done with
5485952Speter   it.  */
5585952Speter
5685952Speterextern struct dictionary *dict_create_hashed_expandable (void);
5785679Speter
5885679Speter/* Create a dictionary implemented via a fixed-size array.  All memory
5985952Speter   it uses is allocated on OBSTACK; the environment is initialized
6085679Speter   from the SYMBOL_LIST.  The symbols are ordered in the same order
61   that they're found in SYMBOL_LIST.  */
62
63extern 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
72extern 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
82extern void dict_free (struct dictionary *dict);
83
84/* Add a symbol to an expandable dictionary.  */
85
86extern void dict_add_symbol (struct dictionary *dict, struct symbol *sym);
87
88/* Is the dictionary empty?  */
89
90extern 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
97struct 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
110extern 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
118extern 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
124extern 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
136extern 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
142extern 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