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

/* Routines for name->symbol lookups in GDB.
   
   Copyright (C) 2003, 2007, 2008, 2009, 2010, 2011
   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 3 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, see <http://www.gnu.org/licenses/>.  */

#ifndef DICTIONARY_H
#define DICTIONARY_H

#include "symfile.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_SEARCH_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_SEARCH_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);

/* Initialize ITERATOR to point at the first symbol in DICT whose
   SYMBOL_SEARCH_NAME is NAME, as tested using COMPARE (which must use
   the same conventions as strcmp_iw and be compatible with any
   dictionary hashing function), and return that first symbol, or NULL
   if there are no such symbols.  */

extern struct symbol *dict_iter_match_first (const struct dictionary *dict,
					     const char *name,
					     symbol_compare_ftype *compare,
					     struct dict_iterator *iterator);

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

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