a1ebd24ebdaf0a5bab72a099e8e4b5b11c6c5a13
[kopensolaris-gnu/glibc.git] / misc / search.h
1 /* Declarations for System V style searching functions.
2    Copyright (C) 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
3    This file is part of the GNU C Library.
4
5    The GNU C Library is free software; you can redistribute it and/or
6    modify it under the terms of the GNU Library General Public License as
7    published by the Free Software Foundation; either version 2 of the
8    License, or (at your option) any later version.
9
10    The GNU C Library is distributed in the hope that it will be useful,
11    but WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13    Library General Public License for more details.
14
15    You should have received a copy of the GNU Library General Public
16    License along with the GNU C Library; see the file COPYING.LIB.  If not,
17    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18    Boston, MA 02111-1307, USA.  */
19
20 #ifndef _SEARCH_H
21 #define _SEARCH_H 1
22
23 #include <features.h>
24
25 #define __need_size_t
26 #define __need_NULL
27 #include <stddef.h>
28
29 __BEGIN_DECLS
30
31 #if defined __USE_SVID || defined __USE_XOPEN_EXTENDED
32 /* Prototype structure for a linked-list data structure.
33    This is the type used by the `insque' and `remque' functions.  */
34
35 struct qelem
36   {
37     struct qelem *q_forw;
38     struct qelem *q_back;
39     char q_data[1];
40   };
41
42
43 /* Insert ELEM into a doubly-linked list, after PREV.  */
44 extern void insque __P ((void *__elem, void *__prev));
45
46 /* Unlink ELEM from the doubly-linked list that it is in.  */
47 extern void remque __P ((void *__elem));
48 #endif
49
50
51 /* For use with hsearch(3).  */
52 #ifndef __COMPAR_FN_T
53 # define __COMPAR_FN_T
54 typedef int (*__compar_fn_t) __P ((__const __ptr_t, __const __ptr_t));
55
56 # ifdef __USE_GNU
57 typedef __compar_fn_t comparison_fn_t;
58 # endif
59 #endif
60
61 /* Action which shall be performed in the call the hsearch.  */
62 typedef enum
63   {
64     FIND,
65     ENTER
66   }
67 ACTION;
68
69 typedef struct entry
70   {
71     char *key;
72     char *data;
73   }
74 ENTRY;
75
76 /* Opaque type for internal use.  */
77 struct _ENTRY;
78
79 /* Family of hash table handling functions.  The functions also
80    have reentrant counterparts ending with _r.  The non-reentrant
81    functions all work on a signle internal hashing table.  */
82
83 /* Search for entry matching ITEM.key in internal hash table.  If
84    ACTION is `FIND' return found entry or signal error by returning
85    NULL.  If ACTION is `ENTER' replace existing data (if any) with
86    ITEM.data.  */
87 extern ENTRY *hsearch __P ((ENTRY __item, ACTION __action));
88
89 /* Create a new hashing table which will at most contain NEL elements.  */
90 extern int hcreate __P ((size_t __nel));
91
92 /* Destroy current internal hashing table.  */
93 extern void __hdestroy __P ((void));
94 extern void hdestroy __P ((void));
95
96 #ifdef __USE_GNU
97 /* Data type for reentrant functions.  */
98 struct hsearch_data
99   {
100     struct _ENTRY *table;
101     unsigned int size;
102     unsigned int filled;
103   };
104
105 /* Reentrant versions which can handle multiple hashing tables at the
106    same time.  */
107 extern int hsearch_r __P ((ENTRY __item, ACTION __action, ENTRY **__retval,
108                            struct hsearch_data *__htab));
109 extern int hcreate_r __P ((size_t __nel, struct hsearch_data *htab));
110 extern void hdestroy_r __P ((struct hsearch_data *htab));
111 #endif
112
113
114 /* The tsearch routines are very interesting. They make many
115    assumptions about the compiler.  It assumes that the first field
116    in node must be the "key" field, which points to the datum.
117    Everything depends on that.  */
118 /* For tsearch */
119 typedef enum
120 {
121   preorder,
122   postorder,
123   endorder,
124   leaf
125 }
126 VISIT;
127
128 /* Search for an entry matching the given KEY in the tree pointed to
129    by *ROOTP and insert a new element if not found.  */
130 extern void *__tsearch __PMT ((__const void *__key, void **__rootp,
131                                __compar_fn_t compar));
132 extern void *tsearch __PMT ((__const void *__key, void **__rootp,
133                              __compar_fn_t compar));
134
135 /* Search for an entry matching the given KEY in the tree pointed to
136    by *ROOTP.  If no matching entry is available return NULL.  */
137 extern void *__tfind __PMT ((__const void *__key, void *__const *__rootp,
138                              __compar_fn_t compar));
139 extern void *tfind __PMT ((__const void *__key, void *__const *__rootp,
140                            __compar_fn_t compar));
141
142 /* Remove the element matching KEY from the tree pointed to by *ROOTP.  */
143 extern void *__tdelete __PMT ((__const void *__key, void **__rootp,
144                                __compar_fn_t compar));
145 extern void *tdelete __PMT ((__const void *__key, void **__rootp,
146                              __compar_fn_t compar));
147
148 #ifndef __ACTION_FN_T
149 # define __ACTION_FN_T
150 typedef void (*__action_fn_t) __P ((__const void *__nodep,
151                                     VISIT __value,
152                                     int __level));
153 #endif
154
155 /* Walk through the whole tree and call the ACTION callback for every node
156    or leaf.  */
157 extern void __twalk __PMT ((__const void *__root, __action_fn_t action));
158 extern void twalk __PMT ((__const void *__root, __action_fn_t action));
159
160 #ifdef __USE_GNU
161 /* Callback type for function to free a tree node.  If the keys are atomic
162    data this function should do nothing.  */
163 typedef void (*__free_fn_t) __P ((void *__nodep));
164
165 /* Destroy the whole tree, call FREEFCT for each node or leaf.  */
166 extern void __tdestroy __PMT ((void *__root, __free_fn_t freefct));
167 extern void tdestroy __PMT ((void *__root, __free_fn_t freefct));
168 #endif
169
170
171 /* Perform linear search for KEY by comparing by COMPAR in an array
172    [BASE,BASE+NMEMB*SIZE).  */
173 extern void *lfind __PMT ((__const void *__key, __const void *__base,
174                            size_t *__nmemb, size_t __size,
175                            __compar_fn_t __compar));
176
177 /* Perform linear search for KEY by comparing by COMPAR function in
178    array [BASE,BASE+NMEMB*SIZE) and insert entry if not found.  */
179 extern void *lsearch __PMT ((__const void *__key, void *__base,
180                              size_t *__nmemb, size_t __size,
181                              __compar_fn_t __compar));
182
183 __END_DECLS
184
185 #endif /* search.h */