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

/* Routines for name->symbol lookups in GDB.
   
   Copyright (C) 2003-2018 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;
struct language_defn;

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

/* Create a dictionary of symbols of language LANGUAGE 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,
					      enum language language,
					      const struct pending
					      *symbol_list);

/* Create a dictionary of symbols of language LANGUAGE, 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 (enum language language);

/* Create a dictionary of symbols of language LANGUAGE, 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,
					      enum language language,
					      const struct pending
					      *symbol_list);

/* Create a dictionary of symbols of language LANGUAGE, 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 (enum language language);

/* 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);

/* Utility to add a list of symbols to a dictionary.  */

extern void dict_add_pending (struct dictionary *dict,
			      const struct pending *symbol_list);

/* 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 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 lookup_name_info &name,
					     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 lookup_name_info &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
e2882c85	3	Copyright (C) 2003-2018 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
a9762ec7 JB	12	the Free Software Foundation; either version 3 of the License, or
a9762ec7 JB	13	(at your option) any later version.
de4f826b	14
a9762ec7 JB	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.
de4f826b DC	19
de4f826b DC	20	You should have received a copy of the GNU General Public License
a9762ec7	21	along with this program. If not, see <http://www.gnu.org/licenses/>. */
de4f826b DC	22
	23	#ifndef DICTIONARY_H
	24	#define DICTIONARY_H
	25
2edb89d3 JK	26	#include "symfile.h"
2edb89d3 JK	27
de4f826b DC	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;
5ffa0793	38	struct language_defn;
de4f826b DC	39
	40	/* The creation functions for various implementations of
	41	dictionaries. */
	42
5ffa0793 PA	43	/* Create a dictionary of symbols of language LANGUAGE implemented via
	44	a fixed-size hashtable. All memory it uses is allocated on
	45	OBSTACK; the environment is initialized from SYMBOL_LIST. */
de4f826b DC	46
de4f826b DC	47	extern struct dictionary dict_create_hashed (struct obstack obstack,
5ffa0793	48	enum language language,
de4f826b DC	49	const struct pending
	50	*symbol_list);
	51
5ffa0793 PA	52	/* Create a dictionary of symbols of language LANGUAGE, implemented
	53	via a hashtable that grows as necessary. The dictionary is
	54	initially empty; to add symbols to it, call dict_add_symbol().
	55	Call dict_free() when you're done with it. */
de4f826b	56
5ffa0793 PA	57	extern struct dictionary *
5ffa0793 PA	58	dict_create_hashed_expandable (enum language language);
de4f826b	59
5ffa0793 PA	60	/* Create a dictionary of symbols of language LANGUAGE, implemented
	61	via a fixed-size array. All memory it uses is allocated on
	62	OBSTACK; the environment is initialized from the SYMBOL_LIST. The
	63	symbols are ordered in the same order that they're found in
	64	SYMBOL_LIST. */
de4f826b DC	65
de4f826b DC	66	extern struct dictionary dict_create_linear (struct obstack obstack,
5ffa0793	67	enum language language,
de4f826b DC	68	const struct pending
	69	*symbol_list);
	70
5ffa0793 PA	71	/* Create a dictionary of symbols of language LANGUAGE, implemented
	72	via an array that grows as necessary. The dictionary is initially
	73	empty; to add symbols to it, call dict_add_symbol(). Call
	74	dict_free() when you're done with it. */
de4f826b	75
5ffa0793 PA	76	extern struct dictionary *
5ffa0793 PA	77	dict_create_linear_expandable (enum language language);
de4f826b DC	78
	79	/* The functions providing the interface to dictionaries. Note that
	80	the most common parts of the interface, namely symbol lookup, are
	81	only provided via iterator functions. */
	82
	83	/* Free the memory used by a dictionary that's not on an obstack. (If
	84	any.) */
	85
	86	extern void dict_free (struct dictionary *dict);
	87
	88	/* Add a symbol to an expandable dictionary. */
	89
	90	extern void dict_add_symbol (struct dictionary dict, struct symbol sym);
	91
0bfa869d DE	92	/* Utility to add a list of symbols to a dictionary. */
	93
	94	extern void dict_add_pending (struct dictionary *dict,
	95	const struct pending *symbol_list);
	96
de4f826b DC	97	/* Is the dictionary empty? */
	98
	99	extern int dict_empty (struct dictionary *dict);
	100
	101	/* A type containing data that is used when iterating over all symbols
	102	in a dictionary. Don't ever look at its innards; this type would
	103	be opaque if we didn't need to be able to allocate it on the
	104	stack. */
	105
	106	struct dict_iterator
	107	{
	108	/* The dictionary that this iterator is associated to. */
	109	const struct dictionary *dict;
	110	/* The next two members are data that is used in a way that depends
	111	on DICT's implementation type. */
	112	int index;
	113	struct symbol *current;
	114	};
	115
	116	/* Initialize ITERATOR to point at the first symbol in DICT, and
	117	return that first symbol, or NULL if DICT is empty. */
	118
	119	extern struct symbol dict_iterator_first (const struct dictionary dict,
	120	struct dict_iterator *iterator);
	121
	122	/* Advance ITERATOR, and return the next symbol, or NULL if there are
	123	no more symbols. Don't call this if you've previously received
	124	NULL from dict_iterator_first or dict_iterator_next on this
	125	iteration. */
	126
	127	extern struct symbol dict_iterator_next (struct dict_iterator iterator);
	128
c4d840bd PH	129	/* Initialize ITERATOR to point at the first symbol in DICT whose
	130	SYMBOL_SEARCH_NAME is NAME, as tested using COMPARE (which must use
	131	the same conventions as strcmp_iw and be compatible with any
	132	dictionary hashing function), and return that first symbol, or NULL
	133	if there are no such symbols. */
	134
	135	extern struct symbol dict_iter_match_first (const struct dictionary dict,
b5ec771e	136	const lookup_name_info &name,
c4d840bd PH	137	struct dict_iterator *iterator);
	138
	139	/* Advance ITERATOR to point at the next symbol in DICT whose
	140	SYMBOL_SEARCH_NAME is NAME, as tested using COMPARE (see
	141	dict_iter_match_first), or NULL if there are no more such symbols.
	142	Don't call this if you've previously received NULL from
	143	dict_iterator_match_first or dict_iterator_match_next on this
0963b4bd	144	iteration. And don't call it unless ITERATOR was created by a
c4d840bd PH	145	previous call to dict_iter_match_first with the same NAME and COMPARE. */
c4d840bd PH	146
b5ec771e	147	extern struct symbol *dict_iter_match_next (const lookup_name_info &name,
c4d840bd PH	148	struct dict_iterator *iterator);
c4d840bd PH	149
de4f826b DC	150	/* Return some notion of the size of the dictionary: the number of
	151	symbols if we have that, the number of hash buckets otherwise. */
	152
	153	extern int dict_size (const struct dictionary *dict);
	154
	155	/* Macro to loop through all symbols in a dictionary DICT, in no
	156	particular order. ITER is a struct dict_iterator (NOTE: __not__ a
	157	struct dict_iterator *), and SYM points to the current symbol.
	158
	159	It's implemented as a single loop, so you can terminate the loop
	160	early by a break if you desire. */
	161
	162	#define ALL_DICT_SYMBOLS(dict, iter, sym) \
	163	for ((sym) = dict_iterator_first ((dict), &(iter)); \
	164	(sym); \
	165	(sym) = dict_iterator_next (&(iter)))
	166
	167	#endif /* DICTIONARY_H */