[deliverable/binutils-gdb.git] / gdb / dictionary.h

/* Routines for name->symbol lookups in GDB.
   
   Copyright (C) 2003, 2007 Free Software Foundation, Inc.

   Contributed by David Carlton <carlton@bactrian.org> and by Kealia,
   Inc.

   This file is part of GDB.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or (at
   your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.  */

#ifndef DICTIONARY_H
#define DICTIONARY_H

/* An opaque type for dictionaries; only dictionary.c should know
   about its innards.  */

struct dictionary;

/* Other types needed for declarations.  */

struct symbol;
struct obstack;
struct pending;


/* The creation functions for various implementations of
   dictionaries.  */

/* Create a dictionary implemented via a fixed-size hashtable.  All
   memory it uses is allocated on OBSTACK; the environment is
   initialized from SYMBOL_LIST.  */

extern struct dictionary *dict_create_hashed (struct obstack *obstack,
					      const struct pending
					      *symbol_list);

/* Create a dictionary implemented via a hashtable that grows as
   necessary.  The dictionary is initially empty; to add symbols to
   it, call dict_add_symbol().  Call dict_free() when you're done with
   it.  */

extern struct dictionary *dict_create_hashed_expandable (void);

/* Create a dictionary implemented via a fixed-size array.  All memory
   it uses is allocated on OBSTACK; the environment is initialized
   from the SYMBOL_LIST.  The symbols are ordered in the same order
   that they're found in SYMBOL_LIST.  */

extern struct dictionary *dict_create_linear (struct obstack *obstack,
					      const struct pending
					      *symbol_list);

/* Create a dictionary implemented via an array that grows as
   necessary.  The dictionary is initially empty; to add symbols to
   it, call dict_add_symbol().  Call dict_free() when you're done with
   it.  */

extern struct dictionary *dict_create_linear_expandable (void);


/* The functions providing the interface to dictionaries.  Note that
   the most common parts of the interface, namely symbol lookup, are
   only provided via iterator functions.  */

/* Free the memory used by a dictionary that's not on an obstack.  (If
   any.)  */

extern void dict_free (struct dictionary *dict);

/* Add a symbol to an expandable dictionary.  */

extern void dict_add_symbol (struct dictionary *dict, struct symbol *sym);

/* Is the dictionary empty?  */

extern int dict_empty (struct dictionary *dict);

/* A type containing data that is used when iterating over all symbols
   in a dictionary.  Don't ever look at its innards; this type would
   be opaque if we didn't need to be able to allocate it on the
   stack.  */

struct dict_iterator
{
  /* The dictionary that this iterator is associated to.  */
  const struct dictionary *dict;
  /* The next two members are data that is used in a way that depends
     on DICT's implementation type.  */
  int index;
  struct symbol *current;
};

/* Initialize ITERATOR to point at the first symbol in DICT, and
   return that first symbol, or NULL if DICT is empty.  */

extern struct symbol *dict_iterator_first (const struct dictionary *dict,
					   struct dict_iterator *iterator);

/* Advance ITERATOR, and return the next symbol, or NULL if there are
   no more symbols.  Don't call this if you've previously received
   NULL from dict_iterator_first or dict_iterator_next on this
   iteration.  */

extern struct symbol *dict_iterator_next (struct dict_iterator *iterator);

/* Initialize ITERATOR to point at the first symbol in DICT whose
   SYMBOL_BEST_NAME is NAME (as tested using strcmp_iw), and return
   that first symbol, or NULL if there are no such symbols.  */

extern struct symbol *dict_iter_name_first (const struct dictionary *dict,
					    const char *name,
					    struct dict_iterator *iterator);

/* Advance ITERATOR to point at the next symbol in DICT whose
   SYMBOL_BEST_NAME is NAME (as tested using strcmp_iw), or NULL if
   there are no more such symbols.  Don't call this if you've
   previously received NULL from dict_iterator_first or
   dict_iterator_next on this iteration.  And don't call it unless
   ITERATOR was created by a previous call to dict_iter_name_first
   with the same NAME.  */

extern struct symbol *dict_iter_name_next (const char *name,
					   struct dict_iterator *iterator);

/* Return some notion of the size of the dictionary: the number of
   symbols if we have that, the number of hash buckets otherwise.  */

extern int dict_size (const struct dictionary *dict);

/* Macro to loop through all symbols in a dictionary DICT, in no
   particular order.  ITER is a struct dict_iterator (NOTE: __not__ a
   struct dict_iterator *), and SYM points to the current symbol.

   It's implemented as a single loop, so you can terminate the loop
   early by a break if you desire.  */

#define ALL_DICT_SYMBOLS(dict, iter, sym)			\
	for ((sym) = dict_iterator_first ((dict), &(iter));	\
	     (sym);						\
	     (sym) = dict_iterator_next (&(iter)))

#endif /* DICTIONARY_H */
Commit	Line	Data
de4f826b DC	1	/* Routines for name->symbol lookups in GDB.
de4f826b DC	2
6aba47ca	3	Copyright (C) 2003, 2007 Free Software Foundation, Inc.
de4f826b DC	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
197e01b6 EZ	22	Foundation, Inc., 51 Franklin Street, Fifth Floor,
197e01b6 EZ	23	Boston, MA 02110-1301, USA. */
de4f826b DC	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 */