misc/search.h

   1 /* Declarations for System V style searching functions.
   2    Copyright (C) 1995-2022 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 Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the 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    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <https://www.gnu.org/licenses/>.  */
  18
  19 #ifndef _SEARCH_H
  20 #define _SEARCH_H 1
  21
  22 #include <features.h>
  23
  24 #define __need_size_t
  25 #include <stddef.h>
  26
  27 __BEGIN_DECLS
  28
  29 #if defined __USE_MISC || defined __USE_XOPEN_EXTENDED
  30 /* Prototype structure for a linked-list data structure.
  31    This is the type used by the `insque' and `remque' functions.  */
  32
  33 # ifdef __USE_GNU
  34 struct qelem
  35   {
  36     struct qelem *q_forw;
  37     struct qelem *q_back;
  38     char q_data[1];
  39   };
  40 # endif
  41
  42
  43 /* Insert ELEM into a doubly-linked list, after PREV.  */
  44 extern void insque (void *__elem, void *__prev) __THROW;
  45
  46 /* Unlink ELEM from the doubly-linked list that it is in.  */
  47 extern void remque (void *__elem) __THROW;
  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) (const void *, const void *);
  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     void *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 (ENTRY __item, ACTION __action) __THROW;
  88
  89 /* Create a new hashing table which will at most contain NEL elements.  */
  90 extern int hcreate (size_t __nel) __THROW;
  91
  92 /* Destroy current internal hashing table.  */
  93 extern void hdestroy (void) __THROW;
  94
  95 #ifdef __USE_GNU
  96 /* Data type for reentrant functions.  */
  97 struct hsearch_data
  98   {
  99     struct _ENTRY *table;
 100     unsigned int size;
 101     unsigned int filled;
 102   };
 103
 104 /* Reentrant versions which can handle multiple hashing tables at the
 105    same time.  */
 106 extern int hsearch_r (ENTRY __item, ACTION __action, ENTRY **__retval,
 107                       struct hsearch_data *__htab) __THROW;
 108 extern int hcreate_r (size_t __nel, struct hsearch_data *__htab) __THROW;
 109 extern void hdestroy_r (struct hsearch_data *__htab) __THROW;
 110 #endif
 111
 112
 113 /* The tsearch routines are very interesting. They make many
 114    assumptions about the compiler.  It assumes that the first field
 115    in node must be the "key" field, which points to the datum.
 116    Everything depends on that.  */
 117 /* For tsearch */
 118 typedef enum
 119 {
 120   preorder,
 121   postorder,
 122   endorder,
 123   leaf
 124 }
 125 VISIT;
 126
 127 /* Search for an entry matching the given KEY in the tree pointed to
 128    by *ROOTP and insert a new element if not found.  */
 129 extern void *tsearch (const void *__key, void **__rootp,
 130                       __compar_fn_t __compar);
 131
 132 /* Search for an entry matching the given KEY in the tree pointed to
 133    by *ROOTP.  If no matching entry is available return NULL.  */
 134 extern void *tfind (const void *__key, void *const *__rootp,
 135                     __compar_fn_t __compar);
 136
 137 /* Remove the element matching KEY from the tree pointed to by *ROOTP.  */
 138 extern void *tdelete (const void *__restrict __key,
 139                       void **__restrict __rootp,
 140                       __compar_fn_t __compar);
 141
 142 #ifndef __ACTION_FN_T
 143 # define __ACTION_FN_T
 144 typedef void (*__action_fn_t) (const void *__nodep, VISIT __value,
 145                                int __level);
 146 #endif
 147
 148 /* Walk through the whole tree and call the ACTION callback for every node
 149    or leaf.  */
 150 extern void twalk (const void *__root, __action_fn_t __action);
 151
 152 #ifdef __USE_GNU
 153 /* Like twalk, but pass down a closure parameter instead of the
 154    level.  */
 155 extern void twalk_r (const void *__root,
 156                      void (*) (const void *__nodep, VISIT __value,
 157                                void *__closure),
 158                      void *__closure);
 159
 160 /* Callback type for function to free a tree node.  If the keys are atomic
 161    data this function should do nothing.  */
 162 typedef void (*__free_fn_t) (void *__nodep);
 163
 164 /* Destroy the whole tree, call FREEFCT for each node or leaf.  */
 165 extern void tdestroy (void *__root, __free_fn_t __freefct);
 166 #endif
 167
 168
 169 /* Perform linear search for KEY by comparing by COMPAR in an array
 170    [BASE,BASE+NMEMB*SIZE).  */
 171 extern void *lfind (const void *__key, const void *__base,
 172                     size_t *__nmemb, size_t __size, __compar_fn_t __compar);
 173
 174 /* Perform linear search for KEY by comparing by COMPAR function in
 175    array [BASE,BASE+NMEMB*SIZE) and insert entry if not found.  */
 176 extern void *lsearch (const void *__key, void *__base,
 177                       size_t *__nmemb, size_t __size, __compar_fn_t __compar);
 178
 179 __END_DECLS
 180
 181 #endif /* search.h */