1 /*************************************************************************************************
2 * The utility API of Tokyo Cabinet
3 * Copyright (C) 2006-2008 Mikio Hirabayashi
4 * This file is part of Tokyo Cabinet.
5 * Tokyo Cabinet is free software; you can redistribute it and/or modify it under the terms of
6 * the GNU Lesser General Public License as published by the Free Software Foundation; either
7 * version 2.1 of the License or any later version. Tokyo Cabinet is distributed in the hope
8 * that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
10 * License for more details.
11 * You should have received a copy of the GNU Lesser General Public License along with Tokyo
12 * Cabinet; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
13 * Boston, MA 02111-1307 USA.
14 *************************************************************************************************/
17 #ifndef _TCUTIL_H /* duplication check */
20 #if defined(__cplusplus)
21 #define __TCUTIL_CLINKAGEBEGIN extern "C" {
22 #define __TCUTIL_CLINKAGEEND }
24 #define __TCUTIL_CLINKAGEBEGIN
25 #define __TCUTIL_CLINKAGEEND
27 __TCUTIL_CLINKAGEBEGIN
37 /*************************************************************************************************
39 *************************************************************************************************/
42 /* String containing the version information. */
43 extern const char *tcversion;
46 /* Pointer to the call back function for handling a fatal error.
47 The argument specifies the error message.
48 The initial value of this variable is `NULL'. If the value is `NULL', the default function is
49 called when a fatal error occurs. A fatal error occurs when memory allocation is failed. */
50 extern void (*tcfatalfunc)(const char *);
53 /* Allocate a region on memory.
54 `size' specifies the size of the region.
55 The return value is the pointer to the allocated region.
56 This function handles failure of memory allocation implicitly. Because the region of the
57 return value is allocated with the `malloc' call, it should be released with the `free' call
58 when it is no longer in use. */
59 void *tcmalloc(size_t size);
62 /* Allocate a nullified region on memory.
63 `nmemb' specifies the number of elements.
64 `size' specifies the size of each element.
65 The return value is the pointer to the allocated nullified region.
66 This function handles failure of memory allocation implicitly. Because the region of the
67 return value is allocated with the `calloc' call, it should be released with the `free' call
68 when it is no longer in use. */
69 void *tccalloc(size_t nmemb, size_t size);
72 /* Re-allocate a region on memory.
73 `ptr' specifies the pointer to the region.
74 `size' specifies the size of the region.
75 The return value is the pointer to the re-allocated region.
76 This function handles failure of memory allocation implicitly. Because the region of the
77 return value is allocated with the `realloc' call, it should be released with the `free' call
78 when it is no longer in use. */
79 void *tcrealloc(void *ptr, size_t size);
82 /* Duplicate a region on memory.
83 `ptr' specifies the pointer to the region.
84 `size' specifies the size of the region.
85 The return value is the pointer to the allocated region of the duplicate.
86 Because an additional zero code is appended at the end of the region of the return value,
87 the return value can be treated as a character string. Because the region of the return
88 value is allocated with the `malloc' call, it should be released with the `free' call when
89 it is no longer in use. */
90 void *tcmemdup(const void *ptr, size_t size);
93 /* Duplicate a string on memory.
94 `str' specifies the string.
95 The return value is the allocated string equivalent to the specified string.
96 Because the region of the return value is allocated with the `malloc' call, it should be
97 released with the `free' call when it is no longer in use. */
98 char *tcstrdup(const void *str);
101 /* Free a region on memory.
102 `ptr' specifies the pointer to the region. If it is `NULL', this function has no effect.
103 Although this function is just a wrapper of `free' call, this is useful in applications using
104 another package of the `malloc' series. */
105 void tcfree(void *ptr);
109 /*************************************************************************************************
111 *************************************************************************************************/
114 typedef struct { /* type of structure for an extensible string object */
115 char *ptr; /* pointer to the region */
116 int size; /* size of the region */
117 int asize; /* size of the allocated region */
121 /* Create an extensible string object.
122 The return value is the new extensible string object. */
123 TCXSTR *tcxstrnew(void);
126 /* Create an extensible string object from a character string.
127 `str' specifies the string of the initial content.
128 The return value is the new extensible string object containing the specified string. */
129 TCXSTR *tcxstrnew2(const char *str);
132 /* Create an extensible string object with the initial allocation size.
133 `asiz' specifies the initial allocation size.
134 The return value is the new extensible string object. */
135 TCXSTR *tcxstrnew3(int asiz);
138 /* Copy an extensible string object.
139 `xstr' specifies the extensible string object.
140 The return value is the new extensible string object equivalent to the specified object. */
141 TCXSTR *tcxstrdup(const TCXSTR *xstr);
144 /* Delete an extensible string object.
145 `xstr' specifies the extensible string object.
146 Note that the deleted object and its derivatives can not be used anymore. */
147 void tcxstrdel(TCXSTR *xstr);
150 /* Concatenate a region to the end of an extensible string object.
151 `xstr' specifies the extensible string object.
152 `ptr' specifies the pointer to the region to be appended.
153 `size' specifies the size of the region. */
154 void tcxstrcat(TCXSTR *xstr, const void *ptr, int size);
157 /* Concatenate a character string to the end of an extensible string object.
158 `xstr' specifies the extensible string object.
159 `str' specifies the string to be appended. */
160 void tcxstrcat2(TCXSTR *xstr, const char *str);
163 /* Get the pointer of the region of an extensible string object.
164 `xstr' specifies the extensible string object.
165 The return value is the pointer of the region of the object.
166 Because an additional zero code is appended at the end of the region of the return value,
167 the return value can be treated as a character string. */
168 const void *tcxstrptr(const TCXSTR *xstr);
171 /* Get the size of the region of an extensible string object.
172 `xstr' specifies the extensible string object.
173 The return value is the size of the region of the object. */
174 int tcxstrsize(const TCXSTR *xstr);
177 /* Clear an extensible string object.
178 `xstr' specifies the extensible string object.
179 The internal buffer of the object is cleared and the size is set zero. */
180 void tcxstrclear(TCXSTR *xstr);
183 /* Convert an extensible string object into a usual allocated region.
184 `xstr' specifies the extensible string object.
185 The return value is the pointer to the allocated region of the object.
186 Because an additional zero code is appended at the end of the region of the return value,
187 the return value can be treated as a character string. Because the region of the return
188 value is allocated with the `malloc' call, it should be released with the `free' call when it
189 is no longer in use. Because the region of the original object is deleted, it should not be
191 void *tcxstrtomalloc(TCXSTR *xstr);
194 /* Create an extensible string object from an allocated region.
195 `ptr' specifies the pointer to the region allocated with `malloc' call.
196 `size' specifies the size of the region.
197 The return value is the new extensible string object wrapping the specified region.
198 Note that the specified region is released when the object is deleted. */
199 TCXSTR *tcxstrfrommalloc(void *ptr, int size);
202 /* Perform formatted output into an extensible string object.
203 `xstr' specifies the extensible string object.
204 `format' specifies the printf-like format string.
205 The conversion character `%' can be used with such flag characters as `s', `d', `o', `u',
206 `x', `X', `c', `e', `E', `f', `g', `G', `@', `?', `%'. `@' works as with `s' but escapes meta
207 characters of XML. `?' works as with `s' but escapes meta characters of URL. The other
208 conversion character work as with each original.
209 The other arguments are used according to the format string. */
210 void tcxstrprintf(TCXSTR *xstr, const char *format, ...);
213 /* Allocate a formatted string on memory.
214 `format' specifies the printf-like format string.
215 The conversion character `%' can be used with such flag characters as `s', `d', `o', `u',
216 `x', `X', `c', `e', `E', `f', `g', `G', `@', `?', `%'. `@' works as with `s' but escapes meta
217 characters of XML. `?' works as with `s' but escapes meta characters of URL. The other
218 conversion character work as with each original.
219 The other arguments are used according to the format string.
220 Because the region of the return value is allocated with the `malloc' call, it should be
221 released with the `free' call when it is no longer in use. */
222 char *tcsprintf(const char *format, ...);
226 /*************************************************************************************************
228 *************************************************************************************************/
231 typedef struct { /* type of structure for an element of a list */
232 char *ptr; /* pointer to the region */
233 int size; /* size of the effective region */
236 typedef struct { /* type of structure for an array list */
237 TCLISTDATUM *array; /* array of data */
238 int anum; /* number of the elements of the array */
239 int start; /* start index of used elements */
240 int num; /* number of used elements */
244 /* Create a list object.
245 The return value is the new list object. */
246 TCLIST *tclistnew(void);
249 /* Create a list object with expecting the number of elements.
250 `anum' specifies the number of elements expected to be stored in the list.
251 The return value is the new list object. */
252 TCLIST *tclistnew2(int anum);
255 /* Copy a list object.
256 `list' specifies the list object.
257 The return value is the new list object equivalent to the specified object. */
258 TCLIST *tclistdup(const TCLIST *list);
261 /* Delete a list object.
262 `list' specifies the list object.
263 Note that the deleted object and its derivatives can not be used anymore. */
264 void tclistdel(TCLIST *list);
267 /* Get the number of elements of a list object.
268 `list' specifies the list object.
269 The return value is the number of elements of the list. */
270 int tclistnum(const TCLIST *list);
273 /* Get the pointer to the region of an element of a list object.
274 `list' specifies the list object.
275 `index' specifies the index of the element.
276 `sp' specifies the pointer to the variable into which the size of the region of the return
278 The return value is the pointer to the region of the value.
279 Because an additional zero code is appended at the end of the region of the return value,
280 the return value can be treated as a character string. If `index' is equal to or more than
281 the number of elements, the return value is `NULL'. */
282 const void *tclistval(const TCLIST *list, int index, int *sp);
285 /* Get the string of an element of a list object.
286 `list' specifies the list object.
287 `index' specifies the index of the element.
288 The return value is the string of the value.
289 If `index' is equal to or more than the number of elements, the return value is `NULL'. */
290 const char *tclistval2(const TCLIST *list, int index);
293 /* Add an element at the end of a list object.
294 `list' specifies the list object.
295 `ptr' specifies the pointer to the region of the new element.
296 `size' specifies the size of the region. */
297 void tclistpush(TCLIST *list, const void *ptr, int size);
300 /* Add a string element at the end of a list object.
301 `list' specifies the list object.
302 `str' specifies the string of the new element. */
303 void tclistpush2(TCLIST *list, const char *str);
306 /* Add an allocated element at the end of a list object.
307 `list' specifies the list object.
308 `ptr' specifies the pointer to the region allocated with `malloc' call.
309 `size' specifies the size of the region.
310 Note that the specified region is released when the object is deleted. */
311 void tclistpushmalloc(TCLIST *list, void *ptr, int size);
314 /* Remove an element of the end of a list object.
315 `list' specifies the list object.
316 `sp' specifies the pointer to the variable into which the size of the region of the return
318 The return value is the pointer to the region of the removed element.
319 Because an additional zero code is appended at the end of the region of the return value,
320 the return value can be treated as a character string. Because the region of the return
321 value is allocated with the `malloc' call, it should be released with the `free' call when it
322 is no longer in use. If the list is empty, the return value is `NULL'. */
323 void *tclistpop(TCLIST *list, int *sp);
326 /* Remove a string element of the end of a list object.
327 `list' specifies the list object.
328 The return value is the string of the removed element.
329 Because the region of the return value is allocated with the `malloc' call, it should be
330 released with the `free' call when it is no longer in use. If the list is empty, the return
332 char *tclistpop2(TCLIST *list);
335 /* Add an element at the top of a list object.
336 `list' specifies the list object.
337 `ptr' specifies the pointer to the region of the new element.
338 `size' specifies the size of the region. */
339 void tclistunshift(TCLIST *list, const void *ptr, int size);
342 /* Add a string element at the top of a list object.
343 `list' specifies the list object.
344 `str' specifies the string of the new element. */
345 void tclistunshift2(TCLIST *list, const char *str);
348 /* Remove an element of the top of a list object.
349 `list' specifies the list object.
350 `sp' specifies the pointer to the variable into which the size of the region of the return
352 The return value is the pointer to the region of the removed element.
353 Because an additional zero code is appended at the end of the region of the return value,
354 the return value can be treated as a character string. Because the region of the return
355 value is allocated with the `malloc' call, it should be released with the `free' call when it
356 is no longer in use. If the list is empty, the return value is `NULL'. */
357 void *tclistshift(TCLIST *list, int *sp);
360 /* Remove a string element of the top of a list object.
361 `list' specifies the list object.
362 The return value is the string of the removed element.
363 Because the region of the return value is allocated with the `malloc' call, it should be
364 released with the `free' call when it is no longer in use. If the list is empty, the return
366 char *tclistshift2(TCLIST *list);
369 /* Add an element at the specified location of a list object.
370 `list' specifies the list object.
371 `index' specifies the index of the new element.
372 `ptr' specifies the pointer to the region of the new element.
373 `size' specifies the size of the region.
374 If `index' is equal to or more than the number of elements, this function has no effect. */
375 void tclistinsert(TCLIST *list, int index, const void *ptr, int size);
378 /* Add a string element at the specified location of a list object.
379 `list' specifies the list object.
380 `index' specifies the index of the new element.
381 `str' specifies the string of the new element.
382 If `index' is equal to or more than the number of elements, this function has no effect. */
383 void tclistinsert2(TCLIST *list, int index, const char *str);
386 /* Remove an element at the specified location of a list object.
387 `list' specifies the list object.
388 `index' specifies the index of the element to be removed.
389 `sp' specifies the pointer to the variable into which the size of the region of the return
391 The return value is the pointer to the region of the removed element.
392 Because an additional zero code is appended at the end of the region of the return value,
393 the return value can be treated as a character string. Because the region of the return
394 value is allocated with the `malloc' call, it should be released with the `free' call when it
395 is no longer in use. If `index' is equal to or more than the number of elements, no element
396 is removed and the return value is `NULL'. */
397 void *tclistremove(TCLIST *list, int index, int *sp);
400 /* Remove a string element at the specified location of a list object.
401 `list' specifies the list object.
402 `index' specifies the index of the element to be removed.
403 The return value is the string of the removed element.
404 Because the region of the return value is allocated with the `malloc' call, it should be
405 released with the `free' call when it is no longer in use. If `index' is equal to or more
406 than the number of elements, no element is removed and the return value is `NULL'. */
407 char *tclistremove2(TCLIST *list, int index);
410 /* Overwrite an element at the specified location of a list object.
411 `list' specifies the list object.
412 `index' specifies the index of the element to be overwritten.
413 `ptr' specifies the pointer to the region of the new content.
414 `size' specifies the size of the new content.
415 If `index' is equal to or more than the number of elements, this function has no effect. */
416 void tclistover(TCLIST *list, int index, const void *ptr, int size);
419 /* Overwrite a string element at the specified location of a list object.
420 `list' specifies the list object.
421 `index' specifies the index of the element to be overwritten.
422 `str' specifies the string of the new content.
423 If `index' is equal to or more than the number of elements, this function has no effect. */
424 void tclistover2(TCLIST *list, int index, const char *str);
427 /* Sort elements of a list object in lexical order.
428 `list' specifies the list object. */
429 void tclistsort(TCLIST *list);
432 /* Sort elements of a list object in case-insensitive lexical order.
433 `list' specifies the list object. */
434 void tclistsortci(TCLIST *list);
437 /* Sort elements of a list object by an arbitrary comparison function.
438 `list' specifies the list object.
439 `cmp' specifies the pointer to the comparison function. The structure TCLISTDATUM has the
440 member "ptr" which is the pointer to the region of the element, and the member "size" which is
441 the size of the region. */
442 void tclistsortex(TCLIST *list, int (*cmp)(const TCLISTDATUM *, const TCLISTDATUM *));
445 /* Search a list object for an element using liner search.
446 `list' specifies the list object.
447 `ptr' specifies the pointer to the region of the key.
448 `size' specifies the size of the region.
449 The return value is the index of a corresponding element or -1 if there is no corresponding
451 If two or more elements correspond, the former returns. */
452 int tclistlsearch(const TCLIST *list, const void *ptr, int size);
455 /* Search a list object for an element using binary search.
456 `list' specifies the list object. It should be sorted in lexical order.
457 `ptr' specifies the pointer to the region of the key.
458 `size' specifies the size of the region.
459 The return value is the index of a corresponding element or -1 if there is no corresponding
461 If two or more elements correspond, which returns is not defined. */
462 int tclistbsearch(const TCLIST *list, const void *ptr, int size);
465 /* Clear a list object.
466 `list' specifies the list object.
467 All elements are removed. */
468 void tclistclear(TCLIST *list);
471 /* Serialize a list object into a byte array.
472 `list' specifies the list object.
473 `sp' specifies the pointer to the variable into which the size of the region of the return
475 The return value is the pointer to the region of the result serial region.
476 Because the region of the return value is allocated with the `malloc' call, it should be
477 released with the `free' call when it is no longer in use. */
478 void *tclistdump(const TCLIST *list, int *sp);
481 /* Create a list object from a serialized byte array.
482 `ptr' specifies the pointer to the region of serialized byte array.
483 `size' specifies the size of the region.
484 The return value is a new list object.
485 Because the object of the return value is created with the function `tclistnew', it should
486 be deleted with the function `tclistdel' when it is no longer in use. */
487 TCLIST *tclistload(const void *ptr, int size);
491 /*************************************************************************************************
493 *************************************************************************************************/
496 typedef struct _TCMAPREC { /* type of structure for an element of a map */
497 int ksiz; /* size of the region of the key */
498 int vsiz; /* size of the region of the value */
499 unsigned int hash; /* second hash value */
500 struct _TCMAPREC *left; /* pointer to the left child */
501 struct _TCMAPREC *right; /* pointer to the right child */
502 struct _TCMAPREC *prev; /* pointer to the previous element */
503 struct _TCMAPREC *next; /* pointer to the next element */
506 typedef struct { /* type of structure for a map */
507 TCMAPREC **buckets; /* bucket array */
508 TCMAPREC *first; /* pointer to the first element */
509 TCMAPREC *last; /* pointer to the last element */
510 TCMAPREC *cur; /* pointer to the current element */
511 uint32_t bnum; /* number of buckets */
512 uint64_t rnum; /* number of records */
513 uint64_t msiz; /* total size of records */
517 /* Create a map object.
518 The return value is the new map object. */
519 TCMAP *tcmapnew(void);
522 /* Create a map object with specifying the number of the buckets.
523 `bnum' specifies the number of the buckets.
524 The return value is the new map object. */
525 TCMAP *tcmapnew2(uint32_t bnum);
528 /* Copy a map object.
529 `map' specifies the map object.
530 The return value is the new map object equivalent to the specified object. */
531 TCMAP *tcmapdup(const TCMAP *map);
534 /* Delete a map object.
535 `map' specifies the map object.
536 Note that the deleted object and its derivatives can not be used anymore. */
537 void tcmapdel(TCMAP *map);
540 /* Store a record into a map object.
541 `map' specifies the map object.
542 `kbuf' specifies the pointer to the region of the key.
543 `ksiz' specifies the size of the region of the key.
544 `vbuf' specifies the pointer to the region of the value.
545 `vsiz' specifies the size of the region of the value.
546 If a record with the same key exists in the map, it is overwritten. */
547 void tcmapput(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
550 /* Store a string record into a map object.
551 `map' specifies the map object.
552 `kstr' specifies the string of the key.
553 `vstr' specifies the string of the value.
554 If a record with the same key exists in the map, it is overwritten. */
555 void tcmapput2(TCMAP *map, const char *kstr, const char *vstr);
558 /* Store a record of the value of two regions into a map object.
559 `map' specifies the map object.
560 `kbuf' specifies the pointer to the region of the key.
561 `ksiz' specifies the size of the region of the key.
562 `fvbuf' specifies the pointer to the former region of the value.
563 `fvsiz' specifies the size of the former region of the value.
564 `lvbuf' specifies the pointer to the latter region of the value.
565 `lvsiz' specifies the size of the latter region of the value.
566 If a record with the same key exists in the map, it is overwritten. */
567 void tcmapput3(TCMAP *map, const char *kbuf, int ksiz,
568 const void *fvbuf, int fvsiz, const char *lvbuf, int lvsiz);
571 /* Store a new record into a map object.
572 `map' specifies the map object.
573 `kbuf' specifies the pointer to the region of the key.
574 `ksiz' specifies the size of the region of the key.
575 `vbuf' specifies the pointer to the region of the value.
576 `vsiz' specifies the size of the region of the value.
577 If successful, the return value is true, else, it is false.
578 If a record with the same key exists in the map, this function has no effect. */
579 bool tcmapputkeep(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
582 /* Store a new string record into a map object.
583 `map' specifies the map object.
584 `kstr' specifies the string of the key.
585 `vstr' specifies the string of the value.
586 If successful, the return value is true, else, it is false.
587 If a record with the same key exists in the map, this function has no effect. */
588 bool tcmapputkeep2(TCMAP *map, const char *kstr, const char *vstr);
591 /* Concatenate a value at the end of the value of the existing record in a map object.
592 `map' specifies the map object.
593 `kbuf' specifies the pointer to the region of the key.
594 `ksiz' specifies the size of the region of the key.
595 `vbuf' specifies the pointer to the region of the value.
596 `vsiz' specifies the size of the region of the value.
597 If there is no corresponding record, a new record is created. */
598 void tcmapputcat(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
601 /* Concatenate a string value at the end of the value of the existing record in a map object.
602 `map' specifies the map object.
603 `kstr' specifies the string of the key.
604 `vstr' specifies the string of the value.
605 If there is no corresponding record, a new record is created. */
606 void tcmapputcat2(TCMAP *map, const char *kstr, const char *vstr);
609 /* Remove a record of a map object.
610 `map' specifies the map object.
611 `kbuf' specifies the pointer to the region of the key.
612 `ksiz' specifies the size of the region of the key.
613 If successful, the return value is true. False is returned when no record corresponds to
614 the specified key. */
615 bool tcmapout(TCMAP *map, const void *kbuf, int ksiz);
618 /* Remove a string record of a map object.
619 `map' specifies the map object.
620 `kstr' specifies the string of the key.
621 If successful, the return value is true. False is returned when no record corresponds to
622 the specified key. */
623 bool tcmapout2(TCMAP *map, const char *kstr);
626 /* Retrieve a record in a map object.
627 `map' specifies the map object.
628 `kbuf' specifies the pointer to the region of the key.
629 `ksiz' specifies the size of the region of the key.
630 `sp' specifies the pointer to the variable into which the size of the region of the return
632 If successful, the return value is the pointer to the region of the value of the
633 corresponding record. `NULL' is returned when no record corresponds.
634 Because an additional zero code is appended at the end of the region of the return value,
635 the return value can be treated as a character string. */
636 const void *tcmapget(const TCMAP *map, const void *kbuf, int ksiz, int *sp);
639 /* Retrieve a string record in a map object.
640 `map' specifies the map object.
641 `kstr' specifies the string of the key.
642 If successful, the return value is the string of the value of the corresponding record.
643 `NULL' is returned when no record corresponds. */
644 const char *tcmapget2(const TCMAP *map, const char *kstr);
647 /* Retrieve a semivolatile record in a map object.
648 `map' specifies the map object.
649 `kbuf' specifies the pointer to the region of the key.
650 `ksiz' specifies the size of the region of the key.
651 `sp' specifies the pointer to the variable into which the size of the region of the return
653 If successful, the return value is the pointer to the region of the value of the
654 corresponding record. `NULL' is returned when no record corresponds.
655 Because an additional zero code is appended at the end of the region of the return value,
656 the return value can be treated as a character string. The internal region of the returned
657 record is moved to the tail so that the record will survive for a time under LRU cache
658 algorithm removing records from the head. */
659 const void *tcmapget3(TCMAP *map, const void *kbuf, int ksiz, int *sp);
662 /* Move a record to the edge of a map object.
663 `map' specifies the map object.
664 `kbuf' specifies the pointer to the region of a key.
665 `ksiz' specifies the size of the region of the key.
666 `head' specifies the destination which is head if it is true or tail if else.
667 If successful, the return value is true. False is returned when no record corresponds to
668 the specified key. */
669 bool tcmapmove(TCMAP *map, const void *kbuf, int ksiz, bool head);
672 /* Move a string record to the edge of a map object.
673 `map' specifies the map object.
674 `kstr' specifies the string of a key.
675 `head' specifies the destination which is head if it is true or tail if else.
676 If successful, the return value is true. False is returned when no record corresponds to
677 the specified key. */
678 bool tcmapmove2(TCMAP *map, const char *kstr, bool head);
681 /* Initialize the iterator of a map object.
682 `map' specifies the map object.
683 The iterator is used in order to access the key of every record stored in the map object. */
684 void tcmapiterinit(TCMAP *map);
687 /* Get the next key of the iterator of a map object.
688 `map' specifies the map object.
689 `sp' specifies the pointer to the variable into which the size of the region of the return
691 If successful, the return value is the pointer to the region of the next key, else, it is
692 `NULL'. `NULL' is returned when no record can be fetched from the iterator.
693 Because an additional zero code is appended at the end of the region of the return value,
694 the return value can be treated as a character string.
695 The order of iteration is assured to be the same as the stored order. */
696 const void *tcmapiternext(TCMAP *map, int *sp);
699 /* Get the next key string of the iterator of a map object.
700 `map' specifies the map object.
701 If successful, the return value is the pointer to the region of the next key, else, it is
702 `NULL'. `NULL' is returned when no record can be fetched from the iterator.
703 The order of iteration is assured to be the same as the stored order. */
704 const char *tcmapiternext2(TCMAP *map);
707 /* Get the value bound to the key fetched from the iterator of a map object.
708 `kbuf' specifies the pointer to the region of the iteration key.
709 `sp' specifies the pointer to the variable into which the size of the region of the return
711 The return value is the pointer to the region of the value of the corresponding record.
712 Because an additional zero code is appended at the end of the region of the return value,
713 the return value can be treated as a character string. */
714 const void *tcmapiterval(const void *kbuf, int *sp);
717 /* Get the value string bound to the key fetched from the iterator of a map object.
718 `kstr' specifies the string of the iteration key.
719 The return value is the pointer to the region of the value of the corresponding record. */
720 const char *tcmapiterval2(const char *kstr);
723 /* Get the number of records stored in a map object.
724 `map' specifies the map object.
725 The return value is the number of the records stored in the map object. */
726 uint64_t tcmaprnum(const TCMAP *map);
729 /* Get the total size of memory used in a map object.
730 `map' specifies the map object.
731 The return value is the total size of memory used in a map object. */
732 uint64_t tcmapmsiz(const TCMAP *map);
735 /* Create a list object containing all keys in a map object.
736 `map' specifies the map object.
737 The return value is the new list object containing all keys in the map object.
738 Because the object of the return value is created with the function `tclistnew', it should
739 be deleted with the function `tclistdel' when it is no longer in use. */
740 TCLIST *tcmapkeys(const TCMAP *map);
743 /* Create a list object containing all values in a map object.
744 `map' specifies the map object.
745 The return value is the new list object containing all values in the map object.
746 Because the object of the return value is created with the function `tclistnew', it should
747 be deleted with the function `tclistdel' when it is no longer in use. */
748 TCLIST *tcmapvals(const TCMAP *map);
751 /* Add an integer to a record in a map object.
752 `map' specifies the map object.
753 `kbuf' specifies the pointer to the region of the key.
754 `ksiz' specifies the size of the region of the key.
755 `num' specifies the additional value.
756 If the corresponding record exists, the value is treated as a integer and is added to. If no
757 record corresponds, a new record of the additional value is stored. */
758 void tcmapaddint(TCMAP *map, const char *kbuf, int ksiz, int num);
761 /* Clear a map object.
762 `map' specifies the map object.
763 All records are removed. */
764 void tcmapclear(TCMAP *map);
767 /* Remove front records of a map object.
768 `map' specifies the map object.
769 `num' specifies the number of records to be removed.
770 If successful, the return value is true. False is returned when no record corresponds to
771 the specified key. */
772 void tcmapcutfront(TCMAP *map, int num);
775 /* Serialize a map object into a byte array.
776 `map' specifies the map object.
777 `sp' specifies the pointer to the variable into which the size of the region of the return
779 The return value is the pointer to the region of the result serial region.
780 Because the region of the return value is allocated with the `malloc' call, it should be
781 released with the `free' call when it is no longer in use. */
782 void *tcmapdump(const TCMAP *map, int *sp);
785 /* Create a map object from a serialized byte array.
786 `ptr' specifies the pointer to the region of serialized byte array.
787 `size' specifies the size of the region.
788 The return value is a new map object.
789 Because the object of the return value is created with the function `tcmapnew', it should be
790 deleted with the function `tcmapdel' when it is no longer in use. */
791 TCMAP *tcmapload(const void *ptr, int size);
794 /* Extract a map record from a serialized byte array.
795 `ptr' specifies the pointer to the region of serialized byte array.
796 `size' specifies the size of the region.
797 `kbuf' specifies the pointer to the region of the key.
798 `ksiz' specifies the size of the region of the key.
799 `sp' specifies the pointer to the variable into which the size of the region of the return
801 If successful, the return value is the pointer to the region of the value of the
802 corresponding record. `NULL' is returned when no record corresponds.
803 Because an additional zero code is appended at the end of the region of the return value,
804 the return value can be treated as a character string. */
805 void *tcmaploadone(const void *ptr, int size, const void *kbuf, int ksiz, int *sp);
809 /*************************************************************************************************
811 *************************************************************************************************/
814 typedef struct { /* type of structure for a on-memory database */
815 void **mmtxs; /* mutexes for method */
816 void *imtx; /* mutex for iterator */
817 TCMAP **maps; /* internal map object */
818 int iter; /* index of maps for the iterator */
822 /* Create an on-memory database object.
823 The return value is the new on-memory database object.
824 The object can be shared by plural threads because of the internal mutex. */
825 TCMDB *tcmdbnew(void);
828 /* Create an on-memory database object with specifying the number of the buckets.
829 `bnum' specifies the number of the buckets.
830 The return value is the new on-memory database object.
831 The object can be shared by plural threads because of the internal mutex. */
832 TCMDB *tcmdbnew2(uint32_t bnum);
835 /* Delete an on-memory database object.
836 `mdb' specifies the on-memory database object. */
837 void tcmdbdel(TCMDB *mdb);
840 /* Store a record into an on-memory database object.
841 `mdb' specifies the on-memory database object.
842 `kbuf' specifies the pointer to the region of the key.
843 `ksiz' specifies the size of the region of the key.
844 `vbuf' specifies the pointer to the region of the value.
845 `vsiz' specifies the size of the region of the value.
846 If a record with the same key exists in the database, it is overwritten. */
847 void tcmdbput(TCMDB *mdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
850 /* Store a string record into an on-memory database object.
851 `mdb' specifies the on-memory database object.
852 `kstr' specifies the string of the key.
853 `vstr' specifies the string of the value.
854 If a record with the same key exists in the database, it is overwritten. */
855 void tcmdbput2(TCMDB *mdb, const char *kstr, const char *vstr);
858 /* Store a record of the value of two regions into an on-memory database object.
859 `mdb' specifies the on-memory database object.
860 `kbuf' specifies the pointer to the region of the key.
861 `ksiz' specifies the size of the region of the key.
862 `fvbuf' specifies the pointer to the former region of the value.
863 `fvsiz' specifies the size of the former region of the value.
864 `lvbuf' specifies the pointer to the latter region of the value.
865 `lvsiz' specifies the size of the latter region of the value.
866 If a record with the same key exists in the database, it is overwritten. */
867 void tcmdbput3(TCMDB *mdb, const char *kbuf, int ksiz,
868 const void *fvbuf, int fvsiz, const char *lvbuf, int lvsiz);
871 /* Store a new record into an on-memory database object.
872 `mdb' specifies the on-memory database object.
873 `kbuf' specifies the pointer to the region of the key.
874 `ksiz' specifies the size of the region of the key.
875 `vbuf' specifies the pointer to the region of the value.
876 `vsiz' specifies the size of the region of the value.
877 If successful, the return value is true, else, it is false.
878 If a record with the same key exists in the database, this function has no effect. */
879 bool tcmdbputkeep(TCMDB *mdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
882 /* Store a new string record into an on-memory database object.
883 `mdb' specifies the on-memory database object.
884 `kstr' specifies the string of the key.
885 `vstr' specifies the string of the value.
886 If successful, the return value is true, else, it is false.
887 If a record with the same key exists in the database, this function has no effect. */
888 bool tcmdbputkeep2(TCMDB *mdb, const char *kstr, const char *vstr);
891 /* Concatenate a value at the end of the value of the existing record in an on-memory database.
892 `mdb' specifies the on-memory database object.
893 `kbuf' specifies the pointer to the region of the key.
894 `ksiz' specifies the size of the region of the key.
895 `vbuf' specifies the pointer to the region of the value.
896 `vsiz' specifies the size of the region of the value.
897 If there is no corresponding record, a new record is created. */
898 void tcmdbputcat(TCMDB *mdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
901 /* Concatenate a string at the end of the value of the existing record in an on-memory database.
902 `mdb' specifies the on-memory database object.
903 `kstr' specifies the string of the key.
904 `vstr' specifies the string of the value.
905 If there is no corresponding record, a new record is created. */
906 void tcmdbputcat2(TCMDB *mdb, const char *kstr, const char *vstr);
909 /* Remove a record of an on-memory database object.
910 `mdb' specifies the on-memory database object.
911 `kbuf' specifies the pointer to the region of the key.
912 `ksiz' specifies the size of the region of the key.
913 If successful, the return value is true. False is returned when no record corresponds to
914 the specified key. */
915 bool tcmdbout(TCMDB *mdb, const void *kbuf, int ksiz);
918 /* Remove a string record of an on-memory database object.
919 `mdb' specifies the on-memory database object.
920 `kstr' specifies the string of the key.
921 If successful, the return value is true. False is returned when no record corresponds to
922 the specified key. */
923 bool tcmdbout2(TCMDB *mdb, const char *kstr);
926 /* Retrieve a record in an on-memory database object.
927 `mdb' specifies the on-memory database object.
928 `kbuf' specifies the pointer to the region of the key.
929 `ksiz' specifies the size of the region of the key.
930 `sp' specifies the pointer to the variable into which the size of the region of the return
932 If successful, the return value is the pointer to the region of the value of the
933 corresponding record. `NULL' is returned when no record corresponds.
934 Because an additional zero code is appended at the end of the region of the return value,
935 the return value can be treated as a character string. Because the region of the return
936 value is allocated with the `malloc' call, it should be released with the `free' call when
937 it is no longer in use. */
938 void *tcmdbget(TCMDB *mdb, const void *kbuf, int ksiz, int *sp);
941 /* Retrieve a string record in an on-memory database object.
942 `mdb' specifies the on-memory database object.
943 `kstr' specifies the string of the key.
944 If successful, the return value is the string of the value of the corresponding record.
945 `NULL' is returned when no record corresponds.
946 Because the region of the return value is allocated with the `malloc' call, it should be
947 released with the `free' call when it is no longer in use. */
948 char *tcmdbget2(TCMDB *mdb, const char *kstr);
951 /* Retrieve a record and move it astern in an on-memory database object.
952 `mdb' specifies the on-memory database object.
953 `kbuf' specifies the pointer to the region of the key.
954 `ksiz' specifies the size of the region of the key.
955 `sp' specifies the pointer to the variable into which the size of the region of the return
957 If successful, the return value is the pointer to the region of the value of the
958 corresponding record. `NULL' is returned when no record corresponds.
959 Because an additional zero code is appended at the end of the region of the return value,
960 the return value can be treated as a character string. Because the region of the return value
961 is allocated with the `malloc' call, it should be released with the `free' call when it is no
962 longer in use. The internal region of the returned record is moved to the tail so that the
963 record will survive for a time under LRU cache algorithm removing records from the head. */
964 void *tcmdbget3(TCMDB *mdb, const void *kbuf, int ksiz, int *sp);
967 /* Get the size of the value of a record in an on-memory database object.
968 `mdb' specifies the on-memory database object.
969 `kbuf' specifies the pointer to the region of the key.
970 `ksiz' specifies the size of the region of the key.
971 If successful, the return value is the size of the value of the corresponding record, else,
973 int tcmdbvsiz(TCMDB *mdb, const void *kbuf, int ksiz);
976 /* Get the size of the value of a string record in an on-memory database object.
977 `mdb' specifies the on-memory database object.
978 `kstr' specifies the string of the key.
979 If successful, the return value is the size of the value of the corresponding record, else,
981 int tcmdbvsiz2(TCMDB *mdb, const char *kstr);
984 /* Initialize the iterator of an on-memory database object.
985 `mdb' specifies the on-memory database object.
986 The iterator is used in order to access the key of every record stored in the on-memory
988 void tcmdbiterinit(TCMDB *mdb);
991 /* Get the next key of the iterator of an on-memory database object.
992 `mdb' specifies the on-memory database object.
993 `sp' specifies the pointer to the variable into which the size of the region of the return
995 If successful, the return value is the pointer to the region of the next key, else, it is
996 `NULL'. `NULL' is returned when no record can be fetched from the iterator.
997 Because an additional zero code is appended at the end of the region of the return value,
998 the return value can be treated as a character string. Because the region of the return
999 value is allocated with the `malloc' call, it should be released with the `free' call when
1000 it is no longer in use. The order of iteration is assured to be the same as the stored
1002 void *tcmdbiternext(TCMDB *mdb, int *sp);
1005 /* Get the next key string of the iterator of an on-memory database object.
1006 `mdb' specifies the on-memory database object.
1007 If successful, the return value is the pointer to the region of the next key, else, it is
1008 `NULL'. `NULL' is returned when no record can be fetched from the iterator.
1009 Because the region of the return value is allocated with the `malloc' call, it should be
1010 released with the `free' call when it is no longer in use. The order of iteration is assured
1011 to be the same as the stored order. */
1012 char *tcmdbiternext2(TCMDB *mdb);
1015 /* Get forward matching keys in an on-memory database object.
1016 `mdb' specifies the on-memory database object.
1017 `pbuf' specifies the pointer to the region of the prefix.
1018 `psiz' specifies the size of the region of the prefix.
1019 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is
1021 The return value is a list object of the corresponding keys. This function does never fail
1022 and return an empty list even if no key corresponds.
1023 Because the object of the return value is created with the function `tclistnew', it should be
1024 deleted with the function `tclistdel' when it is no longer in use. Note that this function
1025 may be very slow because every key in the database is scanned. */
1026 TCLIST *tcmdbfwmkeys(TCMDB *mdb, const void *pbuf, int psiz, int max);
1029 /* Get forward matching string keys in an on-memory database object.
1030 `mdb' specifies the on-memory database object.
1031 `pstr' specifies the string of the prefix.
1032 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is
1034 The return value is a list object of the corresponding keys. This function does never fail
1035 and return an empty list even if no key corresponds.
1036 Because the object of the return value is created with the function `tclistnew', it should be
1037 deleted with the function `tclistdel' when it is no longer in use. Note that this function
1038 may be very slow because every key in the database is scanned. */
1039 TCLIST *tcmdbfwmkeys2(TCMDB *mdb, const char *pstr, int max);
1042 /* Get the number of records stored in an on-memory database object.
1043 `mdb' specifies the on-memory database object.
1044 The return value is the number of the records stored in the database. */
1045 uint64_t tcmdbrnum(TCMDB *mdb);
1048 /* Get the total size of memory used in an on-memory database object.
1049 `mdb' specifies the on-memory database object.
1050 The return value is the total size of memory used in the database. */
1051 uint64_t tcmdbmsiz(TCMDB *mdb);
1054 /* Clear an on-memory database object.
1055 `mdb' specifies the on-memory database object.
1056 All records are removed. */
1057 void tcmdbvanish(TCMDB *mdb);
1060 /* Remove front records of an on-memory database object.
1061 `mdb' specifies the on-memory database object.
1062 `num' specifies the number of records to be removed.
1063 If successful, the return value is true. False is returned when no record corresponds to
1064 the specified key. */
1065 void tcmdbcutfront(TCMDB *mdb, int num);
1069 /*************************************************************************************************
1071 *************************************************************************************************/
1074 typedef struct { /* type of an element of memory pool */
1075 void *ptr; /* pointer */
1076 void (*del)(void *); /* deleting function */
1079 typedef struct { /* type of structure for a memory pool object */
1080 void *mutex; /* mutex for operations */
1081 TCMPELEM *elems; /* array of elements */
1082 int anum; /* number of the elements of the array */
1083 int num; /* number of used elements */
1087 /* Create a memory pool object.
1088 The return value is the new memory pool object. */
1089 TCMPOOL *tcmpoolnew(void);
1092 /* Delete a memory pool object.
1093 `mpool' specifies the memory pool object.
1094 Note that the deleted object and its derivatives can not be used anymore. */
1095 void tcmpooldel(TCMPOOL *mpool);
1098 /* Relegate an arbitrary object to a memory pool object.
1099 `mpool' specifies the memory pool object.
1100 `ptr' specifies the pointer to the object to be relegated.
1101 `del' specifies the pointer to the function to delete the object.
1102 This function assures that the specified object is deleted when the memory pool object is
1104 void tcmpoolput(TCMPOOL *mpool, void *ptr, void (*del)(void *));
1107 /* Relegate an allocated region to a memory pool object.
1108 `ptr' specifies the pointer to the region to be relegated.
1109 This function assures that the specified region is released when the memory pool object is
1111 void tcmpoolputptr(TCMPOOL *mpool, void *ptr);
1114 /* Relegate an extensible string object to a memory pool object.
1115 `mpool' specifies the memory pool object.
1116 `xstr' specifies the extensible string object.
1117 This function assures that the specified object is deleted when the memory pool object is
1119 void tcmpoolputxstr(TCMPOOL *mpool, TCXSTR *xstr);
1122 /* Relegate a list object to a memory pool object.
1123 `mpool' specifies the memory pool object.
1124 `list' specifies the list object.
1125 This function assures that the specified object is deleted when the memory pool object is
1127 void tcmpoolputlist(TCMPOOL *mpool, TCLIST *list);
1130 /* Relegate a map object to a memory pool object.
1131 `mpool' specifies the memory pool object.
1132 `map' specifies the map object.
1133 This function assures that the specified object is deleted when the memory pool object is
1135 void tcmpoolputmap(TCMPOOL *mpool, TCMAP *map);
1138 /* Allocate a region relegated to a memory pool object.
1139 `mpool' specifies the memory pool object.
1140 The return value is the pointer to the allocated region under the memory pool. */
1141 void *tcmpoolmalloc(TCMPOOL *mpool, size_t size);
1144 /* Create an extensible string object relegated to a memory pool object.
1145 The return value is the new extensible string object under the memory pool. */
1146 TCXSTR *tcmpoolxstrnew(TCMPOOL *mpool);
1149 /* Create a list object relegated to a memory pool object.
1150 The return value is the new list object under the memory pool. */
1151 TCLIST *tcmpoollistnew(TCMPOOL *mpool);
1154 /* Create a map object relegated to a memory pool object.
1155 The return value is the new map object under the memory pool. */
1156 TCMAP *tcmpoolmapnew(TCMPOOL *mpool);
1159 /* Get the global memory pool object.
1160 The return value is the global memory pool object.
1161 The global memory pool object is a singleton and assured to be deleted when the porcess is
1162 terminating normally. */
1163 TCMPOOL *tcmpoolglobal(void);
1167 /*************************************************************************************************
1168 * miscellaneous utilities
1169 *************************************************************************************************/
1172 /* Get the larger value of two integers.
1173 `a' specifies an integer.
1174 `b' specifies the other integer.
1175 The return value is the larger value of the two. */
1176 long tclmax(long a, long b);
1179 /* Get the lesser value of two integers.
1180 `a' specifies an integer.
1181 `b' specifies the other integer.
1182 The return value is the lesser value of the two. */
1183 long tclmin(long a, long b);
1186 /* Get a random number as long integer based on uniform distribution.
1187 The return value is the random number between 0 and `ULONG_MAX'.
1188 This function uses the random number source device and generates a real random number if
1190 unsigned long tclrand(void);
1193 /* Get a random number as double decimal based on uniform distribution.
1194 The return value is the random number equal to or greater than 0, and less than 1.0.
1195 This function uses the random number source device and generates a real random number if
1197 double tcdrand(void);
1200 /* Get a random number as double decimal based on normal distribution.
1201 `avg' specifies the average.
1202 `sd' specifies the standard deviation.
1203 The return value is the random number.
1204 This function uses the random number source device and generates a real random number if
1206 double tcdrandnd(double avg, double sd);
1209 /* Compare two strings with case insensitive evaluation.
1210 `astr' specifies a string.
1211 `bstr' specifies of the other string.
1212 The return value is positive if the former is big, negative if the latter is big, 0 if both
1214 int tcstricmp(const char *astr, const char *bstr);
1217 /* Check whether a string begins with a key.
1218 `str' specifies the target string.
1219 `key' specifies the forward matching key string.
1220 The return value is true if the target string begins with the key, else, it is false. */
1221 bool tcstrfwm(const char *str, const char *key);
1224 /* Check whether a string begins with a key with case insensitive evaluation.
1225 `str' specifies the target string.
1226 `key' specifies the forward matching key string.
1227 The return value is true if the target string begins with the key, else, it is false. */
1228 bool tcstrifwm(const char *str, const char *key);
1231 /* Check whether a string ends with a key.
1232 `str' specifies the target string.
1233 `key' specifies the backward matching key string.
1234 The return value is true if the target string ends with the key, else, it is false. */
1235 bool tcstrbwm(const char *str, const char *key);
1238 /* Check whether a string ends with a key with case insensitive evaluation.
1239 `str' specifies the target string.
1240 `key' specifies the backward matching key string.
1241 The return value is true if the target string ends with the key, else, it is false. */
1242 bool tcstribwm(const char *str, const char *key);
1245 /* Calculate the edit distance of two strings.
1246 `astr' specifies a string.
1247 `bstr' specifies of the other string.
1248 The return value is the edit distance which is known as the Levenshtein distance. The cost is
1249 calculated by byte. */
1250 int tcstrdist(const char *astr, const char *bstr);
1253 /* Calculate the edit distance of two UTF-8 strings.
1254 `astr' specifies a string.
1255 `bstr' specifies of the other string.
1256 The return value is the edit distance which is known as the Levenshtein distance. The cost is
1257 calculated by Unicode character. */
1258 int tcstrdistutf(const char *astr, const char *bstr);
1261 /* Convert the letters of a string into upper case.
1262 `str' specifies the string to be converted.
1263 The return value is the string itself. */
1264 char *tcstrtoupper(char *str);
1267 /* Convert the letters of a string into lower case.
1268 `str' specifies the string to be converted.
1269 The return value is the string itself. */
1270 char *tcstrtolower(char *str);
1273 /* Cut space characters at head or tail of a string.
1274 `str' specifies the string to be converted.
1275 The return value is the string itself. */
1276 char *tcstrtrim(char *str);
1279 /* Squeeze space characters in a string and trim it.
1280 `str' specifies the string to be converted.
1281 The return value is the string itself. */
1282 char *tcstrsqzspc(char *str);
1285 /* Substitute characters in a string.
1286 `str' specifies the string to be converted.
1287 `rstr' specifies the string containing characters to be replaced.
1288 `sstr' specifies the string containing characters to be substituted.
1289 If the substitute string is shorter then the replacement string, corresponding characters are
1291 char *tcstrsubchr(char *str, const char *rstr, const char *sstr);
1294 /* Count the number of characters in a string of UTF-8.
1295 `str' specifies the string of UTF-8.
1296 The return value is the number of characters in the string. */
1297 int tcstrcntutf(const char *str);
1300 /* Cut a string of UTF-8 at the specified number of characters.
1301 `str' specifies the string of UTF-8.
1302 `num' specifies the number of characters to be kept.
1303 The return value is the string itself. */
1304 char *tcstrcututf(char *str, int num);
1307 /* Convert a UTF-8 string into a UCS-2 array.
1308 `str' specifies the UTF-8 string.
1309 `ary' specifies the pointer to the region into which the result UCS-2 codes are written. The
1310 size of the buffer should be sufficient.
1311 `np' specifies the pointer to a variable into which the number of elements of the result array
1313 void tcstrutftoucs(const char *str, uint16_t *ary, int *np);
1316 /* Convert a UCS-2 array into a UTF-8 string.
1317 `ary' specifies the array of UCS-2 code codes.
1318 `num' specifies the number of the array.
1319 `str' specifies the pointer to the region into which the result UTF-8 string is written. The
1320 size of the buffer should be sufficient. */
1321 void tcstrucstoutf(const uint16_t *ary, int num, char *str);
1324 /* Create a list object by splitting a string.
1325 `str' specifies the source string.
1326 `delim' specifies a string containing delimiting characters.
1327 The return value is a list object of the split elements.
1328 If two delimiters are successive, it is assumed that an empty element is between the two.
1329 Because the object of the return value is created with the function `tclistnew', it should
1330 be deleted with the function `tclistdel' when it is no longer in use. */
1331 TCLIST *tcstrsplit(const char *str, const char *delims);
1334 /* Create a string by joining all elements of a list object.
1335 `list' specifies a list object.
1336 `delim' specifies a delimiting character.
1337 The return value is the result string.
1338 Because the region of the return value is allocated with the `malloc' call, it should be
1339 released with the `free' call when it is no longer in use. */
1340 char *tcstrjoin(TCLIST *list, char delim);
1343 /* Check whether a string matches a regular expression.
1344 `str' specifies the target string.
1345 `regex' specifies the regular expression string. If it begins with `*', the trailing
1346 substring is used as a case-insensitive regular expression.
1347 The return value is true if matching is success, else, it is false. */
1348 bool tcregexmatch(const char *str, const char *regex);
1351 /* Replace each substring matching a regular expression string.
1352 `str' specifies the target string.
1353 `regex' specifies the regular expression string for substrings. If it begins with `*', the
1354 trailing substring is used as a case-insensitive regular expression.
1355 `alt' specifies the alternative string with which each substrings is replaced. Each `&' in
1356 the string is replaced with the matched substring. Each `\' in the string escapes the
1357 following character. Special escapes "\1" through "\9" referring to the corresponding
1358 matching sub-expressions in the regular expression string are supported.
1359 The return value is a new converted string. Even if the regular expression is invalid, a copy
1360 of the original string is returned.
1361 Because the region of the return value is allocated with the `malloc' call, it should be
1362 released with the `free' call when it is no longer in use. */
1363 char *tcregexreplace(const char *str, const char *regex, const char *alt);
1366 /* Get the time of day in seconds.
1367 The return value is the time of day in seconds. The accuracy is in microseconds. */
1368 double tctime(void);
1371 /* Get the Gregorian calendar of a time.
1372 `t' specifies the source time in seconds from the epoch. If it is `INT64_MAX', the current
1374 `jl' specifies the jet lag of a location in seconds. If it is `INT_MAX', the local jet lag is
1376 `yearp' specifies the pointer to a variable to which the year is assigned. If it is `NULL',
1378 `monp' specifies the pointer to a variable to which the month is assigned. If it is `NULL',
1379 it is not used. 1 means January and 12 means December.
1380 `dayp' specifies the pointer to a variable to which the day of the month is assigned. If it
1381 is `NULL', it is not used.
1382 `hourp' specifies the pointer to a variable to which the hours is assigned. If it is `NULL',
1384 `minp' specifies the pointer to a variable to which the minutes is assigned. If it is `NULL',
1386 `secp' specifies the pointer to a variable to which the seconds is assigned. If it is `NULL',
1388 void tccalendar(int64_t t, int jl, int *yearp, int *monp, int *dayp,
1389 int *hourp, int *minp, int *secp);
1392 /* Format a date as a string in W3CDTF.
1393 `t' specifies the source time in seconds from the epoch. If it is `INT64_MAX', the current
1395 `jl' specifies the jet lag of a location in seconds. If it is `INT_MAX', the local jet lag is
1397 `buf' specifies the pointer to the region into which the result string is written. The size
1398 of the buffer should be equal to or more than 48 bytes.
1399 W3CDTF represents a date as "YYYY-MM-DDThh:mm:ddTZD". */
1400 void tcdatestrwww(int64_t t, int jl, char *buf);
1403 /* Format a date as a string in RFC 1123 format.
1404 `t' specifies the source time in seconds from the epoch. If it is `INT64_MAX', the current
1406 `jl' specifies the jet lag of a location in seconds. If it is `INT_MAX', the local jet lag is
1408 `buf' specifies the pointer to the region into which the result string is written. The size
1409 of the buffer should be equal to or more than 48 bytes.
1410 RFC 1123 format represents a date as "Wdy, DD-Mon-YYYY hh:mm:dd TZD". */
1411 void tcdatestrhttp(int64_t t, int jl, char *buf);
1414 /* Get the time value of a date string.
1415 `str' specifies the date string in decimal, hexadecimal, W3CDTF, or RFC 822 (1123). Decimal
1416 can be trailed by "s" for in seconds, "m" for in minutes, "h" for in hours, and "d" for in
1418 The return value is the time value of the date or `INT64_MAX' if the format is invalid. */
1419 int64_t tcstrmktime(const char *str);
1422 /* Get the day of week of a date.
1423 `year' specifies the year of a date.
1424 `mon' specifies the month of the date.
1425 `day' specifies the day of the date.
1426 The return value is the day of week of the date. 0 means Sunday and 6 means Saturday. */
1427 int tcdayofweek(int year, int mon, int day);
1431 /*************************************************************************************************
1432 * filesystem utilities
1433 *************************************************************************************************/
1436 /* Get the canonicalized absolute path of a file.
1437 `path' specifies the path of the file.
1438 The return value is the canonicalized absolute path of a file, or `NULL' if the path is
1440 Because the region of the return value is allocated with the `malloc' call, it should be
1441 released with the `free' call when it is no longer in use. */
1442 char *tcrealpath(const char *path);
1445 /* Read whole data of a file.
1446 `path' specifies the path of the file. If it is `NULL', the standard input is specified.
1447 `limit' specifies the limiting size of reading data. If it is not more than 0, the limitation
1449 `sp' specifies the pointer to the variable into which the size of the region of the return
1450 value is assigned. If it is `NULL', it is not used.
1451 The return value is the pointer to the allocated region of the read data, or `NULL' if the
1452 file could not be opened.
1453 Because an additional zero code is appended at the end of the region of the return value, the
1454 return value can be treated as a character string. Because the region of the return value is
1455 allocated with the `malloc' call, it should be released with the `free' call when when is no
1457 void *tcreadfile(const char *path, int limit, int *sp);
1460 /* Read every line of a file.
1461 `path' specifies the path of the file. If it is `NULL', the standard input is specified.
1462 The return value is a list object of every lines if successful, else it is `NULL'.
1463 Line separators are cut out. Because the object of the return value is created with the
1464 function `tclistnew', it should be deleted with the function `tclistdel' when it is no longer
1466 TCLIST *tcreadfilelines(const char *path);
1469 /* Write data into a file.
1470 `path' specifies the path of the file. If it is `NULL', the standard output is specified.
1471 `ptr' specifies the pointer to the data region.
1472 `size' specifies the size of the region.
1473 If successful, the return value is true, else, it is false. */
1474 bool tcwritefile(const char *path, const void *ptr, int size);
1478 `src' specifies the path of the source file.
1479 `dest' specifies the path of the destination file.
1480 The return value is true if successful, else, it is false.
1481 If the destination file exists, it is overwritten. */
1482 bool tccopyfile(const char *src, const char *dest);
1485 /* Read names of files in a directory.
1486 `path' specifies the path of the directory.
1487 The return value is a list object of names if successful, else it is `NULL'.
1488 Links to the directory itself and to the parent directory are ignored.
1489 Because the object of the return value is created with the function `tclistnew', it should
1490 be deleted with the function `tclistdel' when it is no longer in use. */
1491 TCLIST *tcreaddir(const char *path);
1494 /* Expand a pattern into a list of matched paths.
1495 `pattern' specifies the matching pattern.
1496 The return value is a list object of matched paths. If no path is matched, an empty list is
1498 Because the object of the return value is created with the function `tclistnew', it should
1499 be deleted with the function `tclistdel' when it is no longer in use. */
1500 TCLIST *tcglobpat(const char *pattern);
1503 /* Remove a file or a directory and its sub ones recursively.
1504 `path' specifies the path of the link.
1505 If successful, the return value is true, else, it is false. False is returned when the link
1506 does not exist or the permission is denied. */
1507 bool tcremovelink(const char *path);
1510 /* Write data into a file.
1511 `fd' specifies the file descriptor.
1512 `buf' specifies the buffer to be written.
1513 `size' specifies the size of the buffer.
1514 The return value is true if successful, else, it is false. */
1515 bool tcwrite(int fd, const void *buf, size_t size);
1518 /* Read data from a file.
1519 `fd' specifies the file descriptor.
1520 `buf' specifies the buffer to store into.
1521 `size' specifies the size of the buffer.
1522 The return value is true if successful, else, it is false. */
1523 bool tcread(int fd, void *buf, size_t size);
1527 `fd' specifies the file descriptor.
1528 `ex' specifies whether an exclusive lock or a shared lock is performed.
1529 `nb' specifies whether to request with non-blocking.
1530 The return value is true if successful, else, it is false. */
1531 bool tclock(int fd, bool ex, bool nb);
1535 /*************************************************************************************************
1536 * encoding utilities
1537 *************************************************************************************************/
1540 /* Encode a serial object with URL encoding.
1541 `ptr' specifies the pointer to the region.
1542 `size' specifies the size of the region.
1543 The return value is the result string.
1544 Because the region of the return value is allocated with the `malloc' call, it should be
1545 released with the `free' call if when is no longer in use. */
1546 char *tcurlencode(const char *ptr, int size);
1549 /* Decode a string encoded with URL encoding.
1550 `str' specifies the encoded string.
1551 `sp' specifies the pointer to a variable into which the size of the region of the return
1553 The return value is the pointer to the region of the result.
1554 Because an additional zero code is appended at the end of the region of the return value,
1555 the return value can be treated as a character string. Because the region of the return
1556 value is allocated with the `malloc' call, it should be released with the `free' call when
1557 it is no longer in use. */
1558 char *tcurldecode(const char *str, int *sp);
1561 /* Break up a URL into elements.
1562 `str' specifies the URL string.
1563 The return value is the map handle whose keys are the name of elements. The key "self"
1564 specifies the URL itself. The key "scheme" specifies the scheme. The key "host" specifies
1565 the host of the server. The key "port" specifies the port number of the server. The key
1566 "authority" specifies the authority information. The key "path" specifies the path of the
1567 resource. The key "file" specifies the file name without the directory section. The key
1568 "query" specifies the query string. The key "fragment" specifies the fragment string.
1569 Supported schema are HTTP, HTTPS, FTP, and FILE. Absolute URL and relative URL are supported.
1570 Because the object of the return value is created with the function `tcmapnew', it should be
1571 deleted with the function `tcmapdel' when it is no longer in use. */
1572 TCMAP *tcurlbreak(const char *str);
1575 /* Resolve a relative URL with an absolute URL.
1576 `base' specifies the absolute URL of the base location.
1577 `target' specifies the URL to be resolved.
1578 The return value is the resolved URL. If the target URL is relative, a new URL of relative
1579 location from the base location is returned. Else, a copy of the target URL is returned.
1580 Because the region of the return value is allocated with the `malloc' call, it should be
1581 released with the `free' call when it is no longer in use. */
1582 char *tcurlresolve(const char *base, const char *target);
1585 /* Encode a serial object with Base64 encoding.
1586 `ptr' specifies the pointer to the region.
1587 `size' specifies the size of the region.
1588 The return value is the result string.
1589 Because the region of the return value is allocated with the `malloc' call, it should be
1590 released with the `free' call if when is no longer in use. */
1591 char *tcbaseencode(const char *ptr, int size);
1594 /* Decode a string encoded with Base64 encoding.
1595 `str' specifies the encoded string.
1596 `sp' specifies the pointer to a variable into which the size of the region of the return
1598 The return value is the pointer to the region of the result.
1599 Because an additional zero code is appended at the end of the region of the return value,
1600 the return value can be treated as a character string. Because the region of the return
1601 value is allocated with the `malloc' call, it should be released with the `free' call when
1602 it is no longer in use. */
1603 char *tcbasedecode(const char *str, int *sp);
1606 /* Encode a serial object with Quoted-printable encoding.
1607 `ptr' specifies the pointer to the region.
1608 `size' specifies the size of the region.
1609 The return value is the result string.
1610 Because the region of the return value is allocated with the `malloc' call, it should be
1611 released with the `free' call if when is no longer in use. */
1612 char *tcquoteencode(const char *ptr, int size);
1615 /* Decode a string encoded with Quoted-printable encoding.
1616 `str' specifies the encoded string.
1617 `sp' specifies the pointer to a variable into which the size of the region of the return
1619 The return value is the pointer to the region of the result.
1620 Because an additional zero code is appended at the end of the region of the return value,
1621 the return value can be treated as a character string. Because the region of the return
1622 value is allocated with the `malloc' call, it should be released with the `free' call when
1623 it is no longer in use. */
1624 char *tcquotedecode(const char *str, int *sp);
1627 /* Encode a string with MIME encoding.
1628 `str' specifies the string.
1629 `encname' specifies the string of the name of the character encoding.
1630 `base' specifies whether to use Base64 encoding. If it is false, Quoted-printable is used.
1631 The return value is the result string.
1632 Because the region of the return value is allocated with the `malloc' call, it should be
1633 released with the `free' call when it is no longer in use. */
1634 char *tcmimeencode(const char *str, const char *encname, bool base);
1637 /* Decode a string encoded with MIME encoding.
1638 `str' specifies the encoded string.
1639 `enp' specifies the pointer to the region into which the name of encoding is written. If it
1640 is `NULL', it is not used. The size of the buffer should be equal to or more than 32 bytes.
1641 The return value is the result string.
1642 Because the region of the return value is allocated with the `malloc' call, it should be
1643 released with the `free' call when it is no longer in use. */
1644 char *tcmimedecode(const char *str, char *enp);
1647 /* Compress a serial object with Packbits encoding.
1648 `ptr' specifies the pointer to the region.
1649 `size' specifies the size of the region.
1650 `sp' specifies the pointer to the variable into which the size of the region of the return
1652 If successful, the return value is the pointer to the result object, else, it is `NULL'.
1653 Because the region of the return value is allocated with the `malloc' call, it should be
1654 released with the `free' call when it is no longer in use. */
1655 char *tcpackencode(const char *ptr, int size, int *sp);
1658 /* Decompress a serial object compressed with Packbits encoding.
1659 `ptr' specifies the pointer to the region.
1660 `size' specifies the size of the region.
1661 `sp' specifies the pointer to a variable into which the size of the region of the return
1663 If successful, the return value is the pointer to the result object, else, it is `NULL'.
1664 Because an additional zero code is appended at the end of the region of the return value,
1665 the return value can be treated as a character string. Because the region of the return
1666 value is allocated with the `malloc' call, it should be released with the `free' call when it
1667 is no longer in use. */
1668 char *tcpackdecode(const char *ptr, int size, int *sp);
1671 /* Compress a serial object with TCBS encoding.
1672 `ptr' specifies the pointer to the region.
1673 `size' specifies the size of the region.
1674 `sp' specifies the pointer to the variable into which the size of the region of the return
1676 If successful, the return value is the pointer to the result object, else, it is `NULL'.
1677 Because the region of the return value is allocated with the `malloc' call, it should be
1678 released with the `free' call when it is no longer in use. */
1679 char *tcbsencode(const char *ptr, int size, int *sp);
1682 /* Decompress a serial object compressed with TCBS encoding.
1683 `ptr' specifies the pointer to the region.
1684 `size' specifies the size of the region.
1685 `sp' specifies the pointer to a variable into which the size of the region of the return
1687 If successful, the return value is the pointer to the result object, else, it is `NULL'.
1688 Because an additional zero code is appended at the end of the region of the return value,
1689 the return value can be treated as a character string. Because the region of the return
1690 value is allocated with the `malloc' call, it should be released with the `free' call when it
1691 is no longer in use. */
1692 char *tcbsdecode(const char *ptr, int size, int *sp);
1695 /* Compress a serial object with Deflate encoding.
1696 `ptr' specifies the pointer to the region.
1697 `size' specifies the size of the region.
1698 `sp' specifies the pointer to the variable into which the size of the region of the return
1700 If successful, the return value is the pointer to the result object, else, it is `NULL'.
1701 Because the region of the return value is allocated with the `malloc' call, it should be
1702 released with the `free' call when it is no longer in use. */
1703 char *tcdeflate(const char *ptr, int size, int *sp);
1706 /* Decompress a serial object compressed with Deflate encoding.
1707 `ptr' specifies the pointer to the region.
1708 `size' specifies the size of the region.
1709 `sp' specifies the pointer to a variable into which the size of the region of the return
1711 If successful, the return value is the pointer to the result object, else, it is `NULL'.
1712 Because an additional zero code is appended at the end of the region of the return value,
1713 the return value can be treated as a character string. Because the region of the return
1714 value is allocated with the `malloc' call, it should be released with the `free' call when it
1715 is no longer in use. */
1716 char *tcinflate(const char *ptr, int size, int *sp);
1719 /* Compress a serial object with GZIP encoding.
1720 `ptr' specifies the pointer to the region.
1721 `size' specifies the size of the region.
1722 `sp' specifies the pointer to the variable into which the size of the region of the return
1724 If successful, the return value is the pointer to the result object, else, it is `NULL'.
1725 Because the region of the return value is allocated with the `malloc' call, it should be
1726 released with the `free' call when it is no longer in use. */
1727 char *tcgzipencode(const char *ptr, int size, int *sp);
1730 /* Decompress a serial object compressed with GZIP encoding.
1731 `ptr' specifies the pointer to the region.
1732 `size' specifies the size of the region.
1733 `sp' specifies the pointer to a variable into which the size of the region of the return
1735 If successful, the return value is the pointer to the result object, else, it is `NULL'.
1736 Because an additional zero code is appended at the end of the region of the return value,
1737 the return value can be treated as a character string. Because the region of the return
1738 value is allocated with the `malloc' call, it should be released with the `free' call when it
1739 is no longer in use. */
1740 char *tcgzipdecode(const char *ptr, int size, int *sp);
1743 /* Get the CRC32 checksum of a serial object.
1744 `ptr' specifies the pointer to the region.
1745 `size' specifies the size of the region.
1746 The return value is the CRC32 checksum of the object. */
1747 unsigned int tcgetcrc(const char *ptr, int size);
1750 /* Encode an array of nonnegative integers with BER encoding.
1751 `ary' specifies the pointer to the array of nonnegative integers.
1752 `anum' specifies the size of the array.
1753 `sp' specifies the pointer to a variable into which the size of the region of the return
1755 The return value is the pointer to the region of the result.
1756 Because the region of the return value is allocated with the `malloc' call, it should be
1757 released with the `free' call if when is no longer in use. */
1758 char *tcberencode(const unsigned int *ary, int anum, int *sp);
1761 /* Decode a serial object encoded with BER encoding.
1762 `ptr' specifies the pointer to the region.
1763 `size' specifies the size of the region.
1764 `np' specifies the pointer to a variable into which the number of elements of the return value
1766 The return value is the pointer to the array of the result.
1767 Because the region of the return value is allocated with the `malloc' call, it should be
1768 released with the `free' call if when is no longer in use. */
1769 unsigned int *tcberdecode(const char *ptr, int size, int *np);
1772 /* Escape meta characters in a string with the entity references of XML.
1773 `str' specifies the string.
1774 The return value is the pointer to the escaped string.
1775 This function escapes only `&', `<', `>', and `"'. Because the region of the return value
1776 is allocated with the `malloc' call, it should be released with the `free' call when it is no
1778 char *tcxmlescape(const char *str);
1781 /* Unescape entity references in a string of XML.
1782 `str' specifies the string.
1783 The return value is the unescaped string.
1784 This function restores only `&', `<', `>', and `"'. Because the region of the
1785 return value is allocated with the `malloc' call, it should be released with the `free' call
1786 when it is no longer in use. */
1787 char *tcxmlunescape(const char *str);
1790 /* Split an XML string into tags and text sections.
1791 `str' specifies the XML string.
1792 The return value is the list object whose elements are strings of tags or text sections.
1793 Because the object of the return value is created with the function `tclistnew', it should
1794 be deleted with the function `tclistdel' when it is no longer in use. Because this function
1795 does not check validation, it can handle also HTML and SGML. */
1796 TCLIST *tcxmlbreak(const char *str);
1799 /* Get the map of attributes of an XML tag.
1800 `str' specifies the pointer to the region of a tag string.
1801 The return value is the map object containing attribute names and their values which are
1802 unescaped. You can get the name of the tag with the key of an empty string.
1803 Because the object of the return value is created with the function `tcmapnew', it should
1804 be deleted with the function `tcmapdel' when it is no longer in use. */
1805 TCMAP *tcxmlattrs(const char *str);
1809 /*************************************************************************************************
1810 * bit operation utilities
1811 *************************************************************************************************/
1814 typedef struct { /* type of structure for a bit stream object */
1815 uint8_t *sp; /* start pointer */
1816 uint8_t *cp; /* current pointer */
1817 int idx; /* bit index */
1818 int size; /* size of used region */
1822 /* Create a bitmap object. */
1823 #define TCBITMAPNEW(TC_num) \
1824 tccalloc(((TC_num) >> 3) + 1, 1);
1827 /* Delete a bitmap object */
1828 #define TCBITMAPDEL(TC_bitmap) \
1830 free((TC_bitmap)); \
1834 /* Turn on a field of a bitmap object. */
1835 #define TCBITMAPON(TC_bitmap, TC_idx) \
1837 (TC_bitmap)[(TC_idx)>>3] |= 0x1 << ((TC_idx) & 0x7); \
1841 /* Turn off a field of a bitmap object. */
1842 #define TCBITMAPOFF(TC_bitmap, TC_idx) \
1844 (TC_bitmap)[(TC_idx)>>3] &= ~(0x1 << ((TC_idx) & 0x7)); \
1848 /* Check a field of a bitmap object. */
1849 #define TCBITMAPCHECK(TC_bitmap, TC_idx) \
1850 ((TC_bitmap)[(TC_idx)>>3] & 0x1 << ((TC_idx) & 0x7))
1853 /* Initialize a bit stream object as writer. */
1854 #define TCBITSTRMINITW(TC_bitstrm, TC_ptr) \
1856 (TC_bitstrm).sp = (uint8_t *)(TC_ptr); \
1857 (TC_bitstrm).cp = (TC_bitstrm).sp; \
1858 *(TC_bitstrm).cp = 0; \
1859 (TC_bitstrm).idx = 3; \
1860 (TC_bitstrm).size = 1; \
1864 /* Concatenate a bit to a bit stream object. */
1865 #define TCBITSTRMCAT(TC_bitstrm, sign) \
1867 if((TC_bitstrm).idx >= 8){ \
1868 *(++(TC_bitstrm).cp) = 0; \
1869 (TC_bitstrm).idx = 0; \
1870 (TC_bitstrm).size++; \
1872 *(TC_bitstrm).cp |= (sign << (TC_bitstrm).idx); \
1873 (TC_bitstrm).idx++; \
1877 /* Set the end mark to a bit stream object. */
1878 #define TCBITSTRMSETEND(TC_bitstrm) \
1880 if((TC_bitstrm).idx >= 8){ \
1881 *(++(TC_bitstrm).cp) = 0; \
1882 (TC_bitstrm).idx = 0; \
1883 (TC_bitstrm).size++; \
1885 *(TC_bitstrm).sp |= (TC_bitstrm).idx & 7; \
1889 /* Get the size of the used region of a bit stream object. */
1890 #define TCBITSTRMSIZE(TC_bitstrm) \
1894 /* Initialize a bit stream object as reader. */
1895 #define TCBITSTRMINITR(TC_bitstrm, TC_ptr, TC_size) \
1897 (TC_bitstrm).sp = (uint8_t *)(TC_ptr); \
1898 (TC_bitstrm).cp = (TC_bitstrm).sp; \
1899 (TC_bitstrm).idx = 3; \
1900 (TC_bitstrm).size = (TC_size); \
1904 /* Read a bit from a bit stream object. */
1905 #define TCBITSTRMREAD(TC_bitstrm, TC_sign) \
1907 if((TC_bitstrm).idx >= 8){ \
1908 (TC_bitstrm).cp++; \
1909 (TC_bitstrm).idx = 0; \
1911 (TC_sign) = (*((TC_bitstrm).cp) & (1 << (TC_bitstrm).idx)) > 0; \
1912 (TC_bitstrm).idx++; \
1916 /* Get the number of bits of a bit stream object. */
1917 #define TCBITSTRMNUM(TC_bitstrm) \
1918 ((((TC_bitstrm).size - 1) << 3) + (*(TC_bitstrm).sp & 7) - 3)
1922 /*************************************************************************************************
1923 * features for experts
1924 *************************************************************************************************/
1929 #define _TC_VERSION "1.2.5"
1930 #define _TC_LIBVER 306
1931 #define _TC_FORMATVER "1.0"
1934 /* Show error message on the standard error output and exit.
1935 `message' specifies an error message.
1936 This function does not return. */
1937 void *tcmyfatal(const char *message);
1940 /* Lock the global mutex object.
1941 If successful, the return value is true, else, it is false. */
1942 bool tcglobalmutexlock(void);
1945 /* Lock the global mutex object by shared locking.
1946 If successful, the return value is true, else, it is false. */
1947 bool tcglobalmutexlockshared(void);
1950 /* Unlock the global mutex object.
1951 If successful, the return value is true, else, it is false. */
1952 bool tcglobalmutexunlock(void);
1955 /* Encode a serial object with BWT encoding.
1956 `ptr' specifies the pointer to the region.
1957 `size' specifies the size of the region.
1958 `idxp' specifies the pointer to the variable into which the index of the original string in
1959 the rotation array is assigned.
1960 The return value is the pointer to the result object.
1961 Because an additional zero code is appended at the end of the region of the return value,
1962 the return value can be treated as a character string. Because the region of the return
1963 value is allocated with the `malloc' call, it should be released with the `free' call when it
1964 is no longer in use. */
1965 char *tcbwtencode(const char *ptr, int size, int *idxp);
1968 /* Decode a serial object encoded with BWT encoding.
1969 `ptr' specifies the pointer to the region.
1970 `size' specifies the size of the region.
1971 `idx' specifies the index of the original string in the rotation array is assigned.
1972 The return value is the pointer to the result object.
1973 Because an additional zero code is appended at the end of the region of the return value,
1974 the return value can be treated as a character string. Because the region of the return
1975 value is allocated with the `malloc' call, it should be released with the `free' call when it
1976 is no longer in use. */
1977 char *tcbwtdecode(const char *ptr, int size, int idx);
1980 /* Print debug information with a formatted string as with `printf'. */
1981 #if __STDC_VERSION__ >= 199901L
1982 #define TCDPRINTF(...) \
1984 fprintf(stderr, "%s:%d:%s: ", __FILE__, __LINE__, __func__); \
1985 fprintf(stderr, __VA_ARGS__); \
1986 fprintf(stderr, "\n"); \
1989 #define TCDPRINTF(TC_str) \
1991 fprintf(stderr, "%s:%d:%s: %s\n", __FILE__, __LINE__, __func__, TC_str); \
1996 /* Print hexadecimal pattern of a binary region. */
1997 #define TCPRINTHEX(TC_ptr, TC_size) \
1999 for(int TC_i = 0; TC_i < (TC_size); TC_i++){ \
2000 if(TC_i > 0) putchar(' '); \
2001 printf("%02X", ((unsigned char *)(TC_ptr))[TC_i]); \
2007 /* Print an extensible string object. */
2008 #define TCPRINTXSTR(TC_xstr) \
2010 fwrite(tcxstrptr((TC_xstr)), tcxstrsize((TC_xstr)), 1, stdout); \
2015 /* Print all elements of a list object. */
2016 #define TCPRINTLIST(TC_list) \
2018 for(int TC_i = 0; TC_i < tclistnum((TC_list)); TC_i++){ \
2020 const char *TC_ptr = tclistval((TC_list), TC_i, &TC_size); \
2021 printf("%p\t", (void *)(TC_list)); \
2022 fwrite(TC_ptr, TC_size, 1, stdout); \
2029 /* Print all records of a list object. */
2030 #define TCPRINTMAP(TC_map) \
2032 TCLIST *TC_keys = tcmapkeys((TC_map)); \
2033 for(int TC_i = 0; TC_i < tclistnum(TC_keys); TC_i++){ \
2035 const char *TC_kbuf = tclistval(TC_keys, TC_i, &TC_ksiz); \
2037 const char *TC_vbuf = tcmapget((TC_map), TC_kbuf, TC_ksiz, &TC_vsiz); \
2038 printf("%p\t", (void *)(TC_map)); \
2039 fwrite(TC_kbuf, TC_ksiz, 1, stdout); \
2041 fwrite(TC_vbuf, TC_vsiz, 1, stdout); \
2045 tclistdel(TC_keys); \
2049 /* Alias of `tcmemdup'. */
2050 #if defined(_MYFASTEST)
2051 #define TCMALLOC(TC_res, TC_size) \
2053 (TC_res) = malloc(TC_size); \
2056 #define TCMALLOC(TC_res, TC_size) \
2058 if(!((TC_res) = malloc(TC_size))) tcmyfatal("out of memory"); \
2062 /* Alias of `tccalloc'. */
2063 #if defined(_MYFASTEST)
2064 #define TCCALLOC(TC_res, TC_nmemb, TC_size) \
2066 (TC_res) = calloc((TC_nmemb), (TC_size)); \
2069 #define TCCALLOC(TC_res, TC_nmemb, TC_size) \
2071 if(!((TC_res) = calloc((TC_nmemb), (TC_size)))) tcmyfatal("out of memory"); \
2075 /* Alias of `tcrealloc'. */
2076 #if defined(_MYFASTEST)
2077 #define TCREALLOC(TC_res, TC_ptr, TC_size) \
2079 (TC_res) = realloc((TC_ptr), (TC_size)); \
2082 #define TCREALLOC(TC_res, TC_ptr, TC_size) \
2084 if(!((TC_res) = realloc((TC_ptr), (TC_size)))) tcmyfatal("out of memory"); \
2088 /* Alias of `tcmemdup'. */
2089 #define TCMEMDUP(TC_res, TC_ptr, TC_size) \
2091 TCMALLOC((TC_res), (TC_size) + 1); \
2092 memcpy((TC_res), (TC_ptr), (TC_size)); \
2093 (TC_res)[TC_size] = '\0'; \
2097 /* Alias of `tcxstrcat'. */
2098 #define TCXSTRCAT(TC_xstr, TC_ptr, TC_size) \
2100 int TC_mysize = (TC_size); \
2101 int TC_nsize = (TC_xstr)->size + TC_mysize + 1; \
2102 if((TC_xstr)->asize < TC_nsize){ \
2103 while((TC_xstr)->asize < TC_nsize){ \
2104 (TC_xstr)->asize *= 2; \
2105 if((TC_xstr)->asize < TC_nsize) (TC_xstr)->asize = TC_nsize; \
2107 TCREALLOC((TC_xstr)->ptr, (TC_xstr)->ptr, (TC_xstr)->asize); \
2109 memcpy((TC_xstr)->ptr + (TC_xstr)->size, (TC_ptr), TC_mysize); \
2110 (TC_xstr)->size += TC_mysize; \
2111 (TC_xstr)->ptr[(TC_xstr)->size] = '\0'; \
2115 /* Alias of `tcxstrptr'. */
2116 #define TCXSTRPTR(TC_xstr) \
2120 /* Alias of `tcxstrsize'. */
2121 #define TCXSTRSIZE(TC_xstr) \
2125 /* Alias of `tclistnum'. */
2126 #define TCLISTNUM(TC_list) \
2130 /* Alias of `tclistval' but not checking size and not using the third parameter. */
2131 #define TCLISTVALPTR(TC_list, TC_index) \
2132 ((void *)((TC_list)->array[(TC_index)+(TC_list)->start].ptr))
2135 /* Alias of `tclistval' but not checking size and returning the size of the value. */
2136 #define TCLISTVALNUM(TC_list, TC_index) \
2137 ((TC_list)->array[(TC_index)+(TC_list)->start].size)
2140 /* Add an element at the end of a list object. */
2141 #define TCLISTPUSH(TC_list, TC_ptr, TC_size) \
2143 int TC_mysize = (TC_size); \
2144 int TC_index = (TC_list)->start + (TC_list)->num; \
2145 if(TC_index >= (TC_list)->anum){ \
2146 (TC_list)->anum += (TC_list)->num + 1; \
2147 TCREALLOC((TC_list)->array, (TC_list)->array, \
2148 (TC_list)->anum * sizeof((TC_list)->array[0])); \
2150 TCLISTDATUM *array = (TC_list)->array; \
2151 TCMALLOC(array[TC_index].ptr, TC_mysize + 1); \
2152 memcpy(array[TC_index].ptr, (TC_ptr), TC_mysize); \
2153 array[TC_index].ptr[TC_mysize] = '\0'; \
2154 array[TC_index].size = TC_mysize; \
2159 /* Alias of `tcmaprnum'. */
2160 #define TCMAPRNUM(TC_map) \
2165 __TCUTIL_CLINKAGEEND
2166 #endif /* duplication check */