1 /* string.c -- String pool for Khepera
2 * Created: Wed Dec 21 21:32:34 1994 by faith@dict.org
3 * Copyright 1994-1997, 2002 Rickard E. Faith (faith@dict.org)
4 * Copyright 2002-2008 Aleksey Cheusov (vle@gmx.net)
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining
7 * a copy of this software and associated documentation files (the
8 * "Software"), to deal in the Software without restriction, including
9 * without limitation the rights to use, copy, modify, merge, publish,
10 * distribute, sublicense, and/or sell copies of the Software, and to
11 * permit persons to whom the Software is furnished to do so, subject to
12 * the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be
15 * included in all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 *
25 * \section{String Pool Routines}
26 *
27 * \intro These routines provide support for string pool objects. In
28 * general, only the |str_find| and |str_findn| functions will be used.
29 * This function takes a pointer to a null-terminated string and returns a
30 * pointer to another null-terminated string which contains the same
31 * information. The pointer returned will be identical for all identical
32 * strings. Memory for string storage is automatically reclaimed at
33 * program termination on systems that support |atexit| or |on_exit|.
34 *
35 */
36
37 #include "maaP.h"
38
39 static str_Pool global;
40
41 typedef struct poolInfo {
42 mem_String string;
43 hsh_HashTable hash;
44 } *poolInfo;
45
46 /* \doc |str_pool_create| initialized a string pool object. */
47
str_pool_create(void)48 str_Pool str_pool_create( void )
49 {
50 poolInfo pool = xmalloc( sizeof( struct poolInfo ) );
51
52 pool->string = mem_create_strings();
53 pool->hash = hsh_create( NULL, NULL );
54
55 return pool;
56 }
57
58 /* \doc |str_pool_destroy| destroys the string pool object, |pool|, and all
59 memory associated with it. */
60
str_pool_destroy(str_Pool pool)61 void str_pool_destroy( str_Pool pool )
62 {
63 poolInfo p = (poolInfo)pool;
64
65 if (!p || !p->string || !p->hash)
66 err_fatal( __func__, "String pool improperly initialized" );
67
68 mem_destroy_strings( p->string );
69 hsh_destroy( p->hash );
70 xfree( p ); /* terminal */
71 }
72
73 /* \doc |str_pool_exists| returns non-zero if the string, |s|, is already
74 in the string pool, |pool|. */
75
str_pool_exists(str_Pool pool,const char * s)76 int str_pool_exists( str_Pool pool, const char *s )
77 {
78 const char *datum;
79 poolInfo p = (poolInfo)pool;
80
81 if ((datum = hsh_retrieve( p->hash, s ))) return 1;
82 return 0;
83 }
84
85 /* \doc |str_pool_find| looks up the string, |s|, in the memory associated
86 with the string pool object, |pool|. If the string is found, a pointer
87 to the previously stored string is returned. Otherwise, the string is
88 copied into string pool memory, and a pointer to the newly allocated
89 memory is returned. */
90
str_pool_find(str_Pool pool,const char * s)91 const char *str_pool_find( str_Pool pool, const char *s )
92 {
93 const char *datum;
94 poolInfo p = (poolInfo)pool;
95
96 if ((datum = hsh_retrieve( p->hash, s ))) return datum;
97 datum = mem_strcpy( p->string, s );
98 hsh_insert( p->hash, datum, datum );
99
100 return datum;
101 }
102
103 /* \doc |str_pool_iterate| is used to iterate a function over every
104 value in the |pool|.
105 The function, |iterator|, is passed the |s|
106 for each entry in the pool. If |iterator| returns a non-zero value,
107 the iterations stop, and |str_pool_iterate| returns non-zero. Note that the
108 keys are in some arbitrary order, and that this order may change between
109 two successive calls to |str_pool_iterate|. */
110
str_pool_iterate(str_Pool pool,int (* iterator)(const char * s))111 int str_pool_iterate(
112 str_Pool pool,
113 int (*iterator)( const char *s ) )
114 {
115 poolInfo p = (poolInfo) pool;
116 hsh_HashTable hash = p -> hash;
117 hsh_Position hash_pos;
118 void *key;
119
120 /* printf ("inside str_pool_iterate\n"); */
121
122 HSH_ITERATE_KEYS (hash, hash_pos, key){
123 if ((*iterator) ((const char *) key))
124 return 1;
125 }
126
127 return 0;
128 }
129
130 /* \doc |str_pool_iterate| is used to iterate a function over every
131 value in the |pool|.
132 The function, |iterator|, is passed the |s|
133 for each entry in the pool. If |iterator| returns a non-zero value,
134 the iterations stop, and |str_pool_iterate| returns non-zero. Note that the
135 keys are in some arbitrary order, and that this order may change between
136 two successive calls to |str_pool_iterate|. */
137
str_pool_iterate_arg(str_Pool pool,int (* iterator)(const char * s,void * arg),void * arg)138 int str_pool_iterate_arg(
139 str_Pool pool,
140 int (*iterator)( const char *s, void *arg ),
141 void *arg )
142 {
143 poolInfo p = (poolInfo) pool;
144 hsh_HashTable hash = p -> hash;
145 hsh_Position hash_pos;
146 void *key;
147
148 HSH_ITERATE_KEYS (hash, hash_pos, key){
149 if ((*iterator) (key, arg)){
150 HSH_ITERATE_END (hash);
151 return 1;
152 }
153 }
154
155 return 0;
156 }
157
str_pool_init_position(str_Pool pool)158 str_Position str_pool_init_position (str_Pool pool)
159 {
160 poolInfo p = (poolInfo) pool;
161
162 return hsh_init_position (p -> hash);
163 }
164
str_pool_next_position(str_Pool pool,str_Position position)165 str_Position str_pool_next_position (str_Pool pool, str_Position position)
166 {
167 poolInfo p = (poolInfo) pool;
168
169 return hsh_next_position (p -> hash, position);
170 }
171
str_pool_get_position(str_Position position,char const * const * key)172 void str_pool_get_position (str_Position position, char const * const*key)
173 {
174 hsh_get_position (position, (void **) __UNCONST(key));
175 }
176
177 /* \doc |str_pool_copy| returns a copy of the string, |s|, using memory
178 from the string pool object, |pool|. This can be used for data that is
179 known to be unique. No checks are made for uniqueness, however; and a
180 pointer to the string is not placed in the hash table. */
181
str_pool_copy(str_Pool pool,const char * s)182 const char *str_pool_copy( str_Pool pool, const char *s )
183 {
184 poolInfo p = (poolInfo)pool;
185
186 return mem_strcpy( p->string, s );
187 }
188
189 /* \doc |str_pool_copyn| returns a copy of the string, |s|, using memory
190 from the string pool object, |pool|. The string will be |length| bytes
191 long, and will be "NULL" terminated. This can be used for data that is
192 known to be unique. No checks are made for uniqueness, however; and a
193 pointer to the string is not placed in the hash table. */
194
str_pool_copyn(str_Pool pool,const char * s,int length)195 const char *str_pool_copyn( str_Pool pool, const char *s, int length )
196 {
197 poolInfo p = (poolInfo)pool;
198
199 return mem_strncpy( p->string, s, length );
200 }
201
202 /* \doc |str_pool_grow| will grow a string in the specified |pool| until
203 |str_pool_finish| is called. There must not be any other calls to
204 modify the specified string |pool| between the first call to
205 |str_pool_grow| and the call to |str_pool_finish|. */
206
str_pool_grow(str_Pool pool,const char * s,int length)207 void str_pool_grow( str_Pool pool, const char *s, int length )
208 {
209 poolInfo p = (poolInfo)pool;
210
211 mem_grow( p->string, s, length );
212 }
213
214 /* \doc |str_pool_finish| will finish the growth of a string performed by
215 multiple calls to |str_pool_grow|. The string will be null terminated
216 and will be entered into the specified string |pool|. Calls to
217 |str_pool_grow| follows by a call to |str_pool_finish| is equivalent to
218 a single call to |str_pool_find|. */
219
str_pool_finish(str_Pool pool)220 const char *str_pool_finish( str_Pool pool )
221 {
222 poolInfo p = (poolInfo)pool;
223 const char *datum;
224
225 mem_grow( p->string, "\0", 1 ); /* guarantee null termination */
226 datum = mem_finish( p->string );
227 hsh_insert( p->hash, datum, datum );
228
229 return datum;
230 }
231
232 /* \doc |str_pool_get_stats| returns statistics about the specified string
233 |pool|. The |str_Stats| structure is shown in \grind{str_Stats}. */
234
str_pool_get_stats(str_Pool pool)235 str_Stats str_pool_get_stats( str_Pool pool )
236 {
237 poolInfo p = (poolInfo)pool;
238 str_Stats s = xmalloc( sizeof( struct str_Stats ) );
239
240 if (p) {
241 mem_StringStats m = mem_get_string_stats( p->string );
242 hsh_Stats h = hsh_get_stats( p->hash );
243
244 s->count = m->count;
245 s->bytes = m->bytes;
246 s->retrievals = h->retrievals;
247 s->hits = h->hits;
248 s->misses = h->misses;
249
250 xfree( h ); /* rare */
251 xfree( m ); /* rare */
252 } else {
253 s->count = 0;
254 s->bytes = 0;
255 s->retrievals = 0;
256 s->hits = 0;
257 s->misses = 0;
258 }
259
260 return s;
261 }
262
263 /* \doc |str_pool_print_stats| prints the statistics for the specified
264 string |pool| on the specified |stream|. If |stream| is "NULL", then
265 "stdout" will be used. */
266
str_pool_print_stats(str_Pool pool,FILE * stream)267 void str_pool_print_stats( str_Pool pool, FILE *stream )
268 {
269 FILE *str = stream ? stream : stdout;
270 str_Stats s = str_pool_get_stats( pool );
271
272 fprintf( str, "Statistics for %sstring pool at %p:\n",
273 pool == global ? "global " : "", pool );
274 fprintf( str, " %d strings using %d bytes\n", s->count, s->bytes );
275 fprintf( str, " %d retrievals (%d from top, %d failed)\n",
276 s->retrievals, s->hits, s->misses );
277 xfree( s ); /* rare */
278 }
279
_str_check_global(void)280 static void _str_check_global( void )
281 {
282 if (!global) global = str_pool_create();
283 }
284
285 /* \doc |str_exists| acts like |str_pool_exists|, except the global string
286 pool is used. */
287
str_exists(const char * s)288 int str_exists( const char *s )
289 {
290 return str_pool_exists( global, s );
291 }
292
293 /* \doc |str_find| acts like |str_pool_find|, except the global string pool
294 is used. If the global string pool has not been initialized, it will be
295 initialized automatically. Further, on systems that support |atexit| or
296 |on_exit|, |str_destroy| will be called automatically at program
297 termination. */
298
str_find(const char * s)299 const char *str_find( const char *s )
300 {
301 _str_check_global();
302 return str_pool_find( global, s );
303 }
304
305 /* \doc |str_findn| acts like |str_find|, except that the length of the
306 string is specified, and the string does not have to be "NULL"
307 terminated. */
308
str_findn(const char * s,int length)309 const char *str_findn( const char *s, int length )
310 {
311 char *tmp = alloca( sizeof( char ) * (length + 1) );
312
313 _str_check_global();
314 strncpy( tmp, s, length);
315 tmp [ length ] = 0;
316
317 return str_pool_find( global, tmp );
318 }
319
320 /* \doc |str_copy| acts like |str_pool_copy|, except the global string pool
321 is used. If the global string pool has not been initialized, it will be
322 initialized automatically. Further, on systems that support |atexit| or
323 |on_exit|, |str_destroy| will be called automatically at program
324 termination. */
325
str_copy(const char * s)326 const char *str_copy( const char *s )
327 {
328 _str_check_global();
329 return str_pool_copy( global, s );
330 }
331
332 /* \doc |str_copyn| acts like |str_copy|, except that the length of the
333 string is specified, and the string does not have to be "NULL"
334 terminated. */
335
str_copyn(const char * s,int length)336 const char *str_copyn( const char *s, int length )
337 {
338 return str_pool_copyn( global, s, length );
339 }
340
341 /* \doc |str_grow| will grow a string until |str_finish| is called. There
342 must not be any other calls to modify the global string pool between the
343 first call to |str_grow| and the call to |str_finish|. */
344
str_grow(const char * s,int length)345 void str_grow( const char *s, int length )
346 {
347 _str_check_global();
348 str_pool_grow( global, s, length );
349 }
350
351 /* \doc |str_finish| will finish the growth of a string performed by
352 multiple calls to |str_grow|. The string will be null terminated and
353 will be entered into the global string pool tables. Calls to |str_grow|
354 follows by a call to |str_finish| is equivalent to a single call to
355 |str_findn|. */
356
str_finish(void)357 const char *str_finish( void )
358 {
359 _str_check_global();
360 return str_pool_finish( global );
361 }
362
363 /* \doc |str_unique| returns a unique string with the given prefix. This
364 is not the most pretty way to generate unique strings, and should be
365 improved. The string is placed in the string pool and does not need to
366 be freed. */
367
str_unique(const char * prefix)368 const char *str_unique( const char *prefix )
369 {
370 static int i = 1;
371 char *buf = alloca( strlen( prefix ) + 100 );
372
373 do {
374 sprintf( buf, "%s%d", prefix, i++ );
375 } while (str_exists( buf ));
376 return str_find( buf );
377 }
378
379 /* \doc |str_destroy| frees all of the memory associated with the global
380 string pool. Since this function is called automatically at program
381 termination on systems that support |atexit| or |on_exit|, there should
382 be no need to call this function explicitly.
383
384 If this function is called explicitly, the next call to |str_find| will
385 re-initialize the global string pool. */
386
str_destroy(void)387 void str_destroy( void )
388 {
389 if (global) str_pool_destroy( global );
390 global = NULL;
391 }
392
393 /* \doc |str_get_stats| returns statistics about the global string pool.
394 The |str_Stats| structure is shown in \grindref{fig:strStats}. */
395
str_get_stats(void)396 str_Stats str_get_stats( void )
397 {
398 return str_pool_get_stats( global );
399 }
400
401 /* \doc |str_print_stats| prints the statistics for the global string pool
402 on the specified |stream|. If |stream| is "NULL", then "stdout" will be
403 used. */
404
str_print_stats(FILE * stream)405 void str_print_stats( FILE *stream )
406 {
407 str_pool_print_stats( global, stream );
408 }
409