gdb/dictionary.h

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