misc/search.h

   1 /* Declarations for System V style searching functions.
   2    Copyright (C) 1995, 1996, 1997, 1998, 1999 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 #include <stddef.h>
  27
  28 __BEGIN_DECLS
  29
  30 #if defined __USE_SVID || defined __USE_XOPEN_EXTENDED
  31 /* Prototype structure for a linked-list data structure.
  32    This is the type used by the `insque' and `remque' functions.  */
  33
  34 struct qelem
  35   {
  36     struct qelem *q_forw;
  37     struct qelem *q_back;
  38     char q_data[1];
  39   };
  40
  41
  42 /* Insert ELEM into a doubly-linked list, after PREV.  */
  43 extern void insque __P ((void *__elem, void *__prev));
  44
  45 /* Unlink ELEM from the doubly-linked list that it is in.  */
  46 extern void remque __P ((void *__elem));
  47 #endif
  48
  49
  50 /* For use with hsearch(3).  */
  51 #ifndef __COMPAR_FN_T
  52 # define __COMPAR_FN_T
  53 typedef int (*__compar_fn_t) __PMT ((__const __ptr_t, __const __ptr_t));
  54
  55 # ifdef __USE_GNU
  56 typedef __compar_fn_t comparison_fn_t;
  57 # endif
  58 #endif
  59
  60 /* Action which shall be performed in the call the hsearch.  */
  61 typedef enum
  62   {
  63     FIND,
  64     ENTER
  65   }
  66 ACTION;
  67
  68 typedef struct entry
  69   {
  70     char *key;
  71     char *data;
  72   }
  73 ENTRY;
  74
  75 /* Opaque type for internal use.  */
  76 struct _ENTRY;
  77
  78 /* Family of hash table handling functions.  The functions also
  79    have reentrant counterparts ending with _r.  The non-reentrant
  80    functions all work on a signle internal hashing table.  */
  81
  82 /* Search for entry matching ITEM.key in internal hash table.  If
  83    ACTION is `FIND' return found entry or signal error by returning
  84    NULL.  If ACTION is `ENTER' replace existing data (if any) with
  85    ITEM.data.  */
  86 extern ENTRY *hsearch __P ((ENTRY __item, ACTION __action));
  87
  88 /* Create a new hashing table which will at most contain NEL elements.  */
  89 extern int hcreate __P ((size_t __nel));
  90
  91 /* Destroy current internal hashing table.  */
  92 extern void hdestroy __P ((void));
  93
  94 #ifdef __USE_GNU
  95 /* Data type for reentrant functions.  */
  96 struct hsearch_data
  97   {
  98     struct _ENTRY *table;
  99     unsigned int size;
 100     unsigned int filled;
 101   };
 102
 103 /* Reentrant versions which can handle multiple hashing tables at the
 104    same time.  */
 105 extern int hsearch_r __P ((ENTRY __item, ACTION __action, ENTRY **__retval,
 106                            struct hsearch_data *__htab));
 107 extern int hcreate_r __P ((size_t __nel, struct hsearch_data *htab));
 108 extern void hdestroy_r __P ((struct hsearch_data *htab));
 109 #endif
 110
 111
 112 /* The tsearch routines are very interesting. They make many
 113    assumptions about the compiler.  It assumes that the first field
 114    in node must be the "key" field, which points to the datum.
 115    Everything depends on that.  */
 116 /* For tsearch */
 117 typedef enum
 118 {
 119   preorder,
 120   postorder,
 121   endorder,
 122   leaf
 123 }
 124 VISIT;
 125
 126 /* Search for an entry matching the given KEY in the tree pointed to
 127    by *ROOTP and insert a new element if not found.  */
 128 extern void *tsearch __PMT ((__const void *__key, void **__rootp,
 129                              __compar_fn_t compar));
 130
 131 /* Search for an entry matching the given KEY in the tree pointed to
 132    by *ROOTP.  If no matching entry is available return NULL.  */
 133 extern void *tfind __PMT ((__const void *__key, void *__const *__rootp,
 134                            __compar_fn_t compar));
 135
 136 /* Remove the element matching KEY from the tree pointed to by *ROOTP.  */
 137 extern void *tdelete __PMT ((__const void *__key, void **__rootp,
 138                              __compar_fn_t compar));
 139
 140 #ifndef __ACTION_FN_T
 141 # define __ACTION_FN_T
 142 typedef void (*__action_fn_t) __PMT ((__const void *__nodep,
 143                                       VISIT __value,
 144                                       int __level));
 145 #endif
 146
 147 /* Walk through the whole tree and call the ACTION callback for every node
 148    or leaf.  */
 149 extern void twalk __PMT ((__const void *__root, __action_fn_t action));
 150
 151 #ifdef __USE_GNU
 152 /* Callback type for function to free a tree node.  If the keys are atomic
 153    data this function should do nothing.  */
 154 typedef void (*__free_fn_t) __PMT ((void *__nodep));
 155
 156 /* Destroy the whole tree, call FREEFCT for each node or leaf.  */
 157 extern void tdestroy __PMT ((void *__root, __free_fn_t freefct));
 158 #endif
 159
 160
 161 /* Perform linear search for KEY by comparing by COMPAR in an array
 162    [BASE,BASE+NMEMB*SIZE).  */
 163 extern void *lfind __PMT ((__const void *__key, __const void *__base,
 164                            size_t *__nmemb, size_t __size,
 165                            __compar_fn_t __compar));
 166
 167 /* Perform linear search for KEY by comparing by COMPAR function in
 168    array [BASE,BASE+NMEMB*SIZE) and insert entry if not found.  */
 169 extern void *lsearch __PMT ((__const void *__key, void *__base,
 170                              size_t *__nmemb, size_t __size,
 171                              __compar_fn_t __compar));
 172
 173 __END_DECLS
 174
 175 #endif /* search.h */