7 .Nm hcreate , hdestroy , hsearch
8 .Nd manage hash search table
14 .Fn hcreate "size_t nel"
18 .Fn hsearch "ENTRY item" "ACTION action"
25 functions manage hash search tables.
29 function allocates sufficient space for the table, and the application should
30 ensure it is called before
35 argument is an estimate of the maximum
36 number of entries that the table should contain.
37 This number may be adjusted upward by the
38 algorithm in order to obtain certain mathematically favorable circumstances.
42 function disposes of the search table, and may be followed by another call to
46 the data can no longer be considered accessible.
51 for each comparison key in the search table
52 but not the data item associated with the key.
56 function is a hash-table search routine.
57 It returns a pointer into a hash table
58 indicating the location at which an entry can be found.
61 argument is a structure of type
65 header) containing two pointers:
67 points to the comparison key (a
73 points to any other data to be associated with
75 The comparison function used by
82 member of an enumeration type
84 indicating the disposition of the entry if it cannot be
89 should be inserted in the table at an
92 indicates that no entry should be made.
93 Unsuccessful resolution is
94 indicated by the return of a
98 The comparison key (passed to
102 must be allocated using
114 function returns 0 if it cannot allocate sufficient space for the table;
115 otherwise, it returns non-zero.
119 function does not return a value.
125 pointer if either the
131 could not be found or the
135 and the table is full.
137 The following example reads in strings followed by two numbers
138 and stores them in a hash table, discarding duplicates.
139 It then reads in strings and finds the matching entry in the hash
140 table and prints it out.
147 struct info { /* This is the info stored in the table */
148 int age, room; /* other than the key. */
151 #define NUM_EMPL 5000 /* # of elements in search table. */
156 char str[BUFSIZ]; /* Space to read string */
157 struct info info_space[NUM_EMPL]; /* Space to store employee info. */
158 struct info *info_ptr = info_space; /* Next space in info_space. */
160 ENTRY *found_item; /* Name to look for in table. */
161 char name_to_find[30];
164 /* Create table; no error checking is performed. */
165 (void) hcreate(NUM_EMPL);
167 while (scanf("%s%d%d", str, &info_ptr->age,
168 &info_ptr->room) != EOF && i++ < NUM_EMPL) {
169 /* Put information in structure, and structure in item. */
170 item.key = strdup(str);
171 item.data = info_ptr;
173 /* Put item into table. */
174 (void) hsearch(item, ENTER);
178 item.key = name_to_find;
179 while (scanf("%s", item.key) != EOF) {
180 if ((found_item = hsearch(item, FIND)) != NULL) {
181 /* If item is in the table. */
182 (void)printf("found %s, age = %d, room = %d\en",
184 ((struct info *)found_item->data)->age,
185 ((struct info *)found_item->data)->room);
187 (void)printf("no such employee %s\en", name_to_find);
198 functions may fail if:
201 Insufficient storage space is available.
223 functions first appeared in
226 The interface permits the use of only one hash table at a time.