1TCUTIL(3) Tokyo Cabinet TCUTIL(3)
2
6 tcutil - the utility API
7
10 The utility API is a set of routines to handle records on memory eas‐
11 ily. Especially, extensible string, array list, hash map, and ordered
12 tree are useful.
13 To use the utility API, include `tcutil.h' and related standard header
15 files. Usually, write the following description near the front of a
16 source file.
17 #include <tcutil.h>
19 #include <stdlib.h>
20 #include <time.h>
21 #include <stdbool.h>
22 #include <stdint.h>
23 Objects whose type is pointer to `TCXSTR' are used for extensible
25 string. An extensible string object is created with the function
26 `tcxstrnew' and is deleted with the function `tcxstrdel'. Objects
27 whose type is pointer to `TCLIST' are used for array list. A list
28 object is created with the function `tclistnew' and is deleted with the
29 function `tclistdel'. Objects whose type is pointer to `TCMAP' are
30 used for hash map. A map object is created with the function `tcmap‐
31 new' and is deleted with the function `tcmapdel'. Objects whose type
32 is pointer to `TCTREE' are used for ordered tree. A tree object is
33 created with the function `tctreenew' and is deleted with the function
34 `tctreedel'. To avoid memory leak, it is important to delete every
35 object when it is no longer in use.
36
39 The constant `tcversion' is the string containing the version informa‐
40 tion.
41 extern const char *tcversion;
43 The variable `tcfatalfunc' is the pointer to the call back function for
45 handling a fatal error.
46 extern void (*tcfatalfunc)(const char *);
48 The argument specifies the error message.
49 The initial value of this variable is `NULL'. If the
50 value is `NULL', the default function is called when a
51 fatal error occurs. A fatal error occurs when memory
52 allocation is failed.
53 The function `tcmalloc' is used in order to allocate a region on mem‐
55 ory.
56 void *tcmalloc(size_t size);
58 `size' specifies the size of the region.
59 The return value is the pointer to the allocated region.
60 This function handles failure of memory allocation
61 implicitly. Because the region of the return value is
62 allocated with the `malloc' call, it should be released
63 with the `free' call when it is no longer in use.
64 The function `tccalloc' is used in order to allocate a nullified region
66 on memory.
67 void *tccalloc(size_t nmemb, size_t size);
69 `nmemb' specifies the number of elements.
70 `size' specifies the size of each element.
71 The return value is the pointer to the allocated nulli‐
72 fied region.
73 This function handles failure of memory allocation
74 implicitly. Because the region of the return value is
75 allocated with the `calloc' call, it should be released
76 with the `free' call when it is no longer in use.
77 The function `tcrealloc' is used in order to re-allocate a region on
79 memory.
80 void *tcrealloc(void *ptr, size_t size);
82 `ptr' specifies the pointer to the region.
83 `size' specifies the size of the region.
84 The return value is the pointer to the re-allocated
85 region.
86 This function handles failure of memory allocation
87 implicitly. Because the region of the return value is
88 allocated with the `realloc' call, it should be released
89 with the `free' call when it is no longer in use.
90 The function `tcmemdup' is used in order to duplicate a region on mem‐
92 ory.
93 void *tcmemdup(const void *ptr, size_t size);
95 `ptr' specifies the pointer to the region.
96 `size' specifies the size of the region.
97 The return value is the pointer to the allocated region
98 of the duplicate.
99 Because an additional zero code is appended at the end of
100 the region of the return value, the return value can be
101 treated as a character string. Because the region of the
102 return value is allocated with the `malloc' call, it
103 should be released with the `free' call when it is no
104 longer in use.
105 The function `tcstrdup' is used in order to duplicate a string on mem‐
107 ory.
108 char *tcstrdup(const void *str);
110 `str' specifies the string.
111 The return value is the allocated string equivalent to
112 the specified string.
113 Because the region of the return value is allocated with
114 the `malloc' call, it should be released with the `free'
115 call when it is no longer in use.
116 The function `tcfree' is used in order to free a region on memory.
118 void tcfree(void *ptr);
120 `ptr' specifies the pointer to the region. If it is
121 `NULL', this function has no effect.
122 Although this function is just a wrapper of `free' call,
123 this is useful in applications using another package of
124 the `malloc' series.
125
128 The function `tcxstrnew' is used in order to create an extensible
129 string object.
130 TCXSTR *tcxstrnew(void);
132 The return value is the new extensible string object.
133 The function `tcxstrnew2' is used in order to create an extensible
135 string object from a character string.
136 TCXSTR *tcxstrnew2(const char *str);
138 `str' specifies the string of the initial content.
139 The return value is the new extensible string object con‐
140 taining the specified string.
141 The function `tcxstrnew3' is used in order to create an extensible
143 string object with the initial allocation size.
144 TCXSTR *tcxstrnew3(int asiz);
146 `asiz' specifies the initial allocation size.
147 The return value is the new extensible string object.
148 The function `tcxstrdup' is used in order to copy an extensible string
150 object.
151 TCXSTR *tcxstrdup(const TCXSTR *xstr);
153 `xstr' specifies the extensible string object.
154 The return value is the new extensible string object
155 equivalent to the specified object.
156 The function `tcxstrdel' is used in order to delete an extensible
158 string object.
159 void tcxstrdel(TCXSTR *xstr);
161 `xstr' specifies the extensible string object.
162 Note that the deleted object and its derivatives can not
163 be used anymore.
164 The function `tcxstrcat' is used in order to concatenate a region to
166 the end of an extensible string object.
167 void tcxstrcat(TCXSTR *xstr, const void *ptr, int size);
169 `xstr' specifies the extensible string object.
170 `ptr' specifies the pointer to the region to be appended.
171 `size' specifies the size of the region.
172 The function `tcxstrcat2' is used in order to concatenate a character
174 string to the end of an extensible string object.
175 void tcxstrcat2(TCXSTR *xstr, const char *str);
177 `xstr' specifies the extensible string object.
178 `str' specifies the string to be appended.
179 The function `tcxstrptr' is used in order to get the pointer of the
181 region of an extensible string object.
182 const void *tcxstrptr(const TCXSTR *xstr);
184 `xstr' specifies the extensible string object.
185 The return value is the pointer of the region of the
186 object.
187 Because an additional zero code is appended at the end of
188 the region of the return value, the return value can be
189 treated as a character string.
190 The function `tcxstrsize' is used in order to get the size of the
192 region of an extensible string object.
193 int tcxstrsize(const TCXSTR *xstr);
195 `xstr' specifies the extensible string object.
196 The return value is the size of the region of the object.
197 The function `tcxstrclear' is used in order to clear an extensible
199 string object.
200 void tcxstrclear(TCXSTR *xstr);
202 `xstr' specifies the extensible string object.
203 The internal buffer of the object is cleared and the size
204 is set zero.
205 The function `tcxstrprintf' is used in order to perform formatted out‐
207 put into an extensible string object.
208 void tcxstrprintf(TCXSTR *xstr, const char *format, ...);
210 `xstr' specifies the extensible string object.
211 `format' specifies the printf-like format string. The
212 conversion character `%' can be used with such flag char‐
213 acters as `s', `d', `o', `u', `x', `X', `c', `e', `E',
214 `f', `g', `G', `@', `?', `b', and `%'. `@' works as with
215 `s' but escapes meta characters of XML. `?' works as
216 with `s' but escapes meta characters of URL. `b' con‐
217 verts an integer to the string as binary numbers. The
218 other conversion character work as with each original.
219 The other arguments are used according to the format
220 string.
221 The function `tcsprintf' is used in order to allocate a formatted
223 string on memory.
224 char *tcsprintf(const char *format, ...);
226 `format' specifies the printf-like format string. The
227 conversion character `%' can be used with such flag char‐
228 acters as `s', `d', `o', `u', `x', `X', `c', `e', `E',
229 `f', `g', `G', `@', `?', `b', and `%'. `@' works as with
230 `s' but escapes meta characters of XML. `?' works as
231 with `s' but escapes meta characters of URL. `b' con‐
232 verts an integer to the string as binary numbers. The
233 other conversion character work as with each original.
234 The other arguments are used according to the format
235 string.
236 The return value is the pointer to the region of the
237 result string.
238 Because the region of the return value is allocated with
239 the `malloc' call, it should be released with the `free'
240 call when it is no longer in use.
241
244 The function `tclistnew' is used in order to create a list object.
245 TCLIST *tclistnew(void);
247 The return value is the new list object.
248 The function `tclistnew2' is used in order to create a list object with
250 expecting the number of elements.
251 TCLIST *tclistnew2(int anum);
253 `anum' specifies the number of elements expected to be
254 stored in the list.
255 The return value is the new list object.
256 The function `tclistnew3' is used in order to create a list object with
258 initial string elements.
259 TCLIST *tclistnew3(const char *str, ...);
261 `str' specifies the string of the first element.
262 The other arguments are other elements. They should be
263 trailed by a `NULL' argument.
264 The return value is the new list object.
265 The function `tclistdup' is used in order to copy a list object.
267 TCLIST *tclistdup(const TCLIST *list);
269 `list' specifies the list object.
270 The return value is the new list object equivalent to the
271 specified object.
272 The function `tclistdel' is used in order to delete a list object.
274 void tclistdel(TCLIST *list);
276 `list' specifies the list object.
277 Note that the deleted object and its derivatives can not
278 be used anymore.
279 The function `tclistnum' is used in order to get the number of elements
281 of a list object.
282 int tclistnum(const TCLIST *list);
284 `list' specifies the list object.
285 The return value is the number of elements of the list.
286 The function `tclistval' is used in order to get the pointer to the
288 region of an element of a list object.
289 const void *tclistval(const TCLIST *list, int index, int *sp);
291 `list' specifies the list object.
292 `index' specifies the index of the element.
293 `sp' specifies the pointer to the variable into which the
294 size of the region of the return value is assigned.
295 The return value is the pointer to the region of the
296 value.
297 Because an additional zero code is appended at the end of
298 the region of the return value, the return value can be
299 treated as a character string. If `index' is equal to or
300 more than the number of elements, the return value is
301 `NULL'.
302 The function `tclistval2' is used in order to get the string of an ele‐
304 ment of a list object.
305 const char *tclistval2(const TCLIST *list, int index);
307 `list' specifies the list object.
308 `index' specifies the index of the element.
309 The return value is the string of the value.
310 If `index' is equal to or more than the number of ele‐
311 ments, the return value is `NULL'.
312 The function `tclistpush' is used in order to add an element at the end
314 of a list object.
315 void tclistpush(TCLIST *list, const void *ptr, int size);
317 `list' specifies the list object.
318 `ptr' specifies the pointer to the region of the new ele‐
319 ment.
320 `size' specifies the size of the region.
321 The function `tclistpush2' is used in order to add a string element at
323 the end of a list object.
324 void tclistpush2(TCLIST *list, const char *str);
326 `list' specifies the list object.
327 `str' specifies the string of the new element.
328 The function `tclistpop' is used in order to remove an element of the
330 end of a list object.
331 void *tclistpop(TCLIST *list, int *sp);
333 `list' specifies the list object.
334 `sp' specifies the pointer to the variable into which the
335 size of the region of the return value is assigned.
336 The return value is the pointer to the region of the
337 removed element.
338 Because an additional zero code is appended at the end of
339 the region of the return value, the return value can be
340 treated as a character string. Because the region of the
341 return value is allocated with the `malloc' call, it
342 should be released with the `free' call when it is no
343 longer in use. If the list is empty, the return value is
344 `NULL'.
345 The function `tclistpop2' is used in order to remove a string element
347 of the end of a list object.
348 char *tclistpop2(TCLIST *list);
350 `list' specifies the list object.
351 The return value is the string of the removed element.
352 Because the region of the return value is allocated with
353 the `malloc' call, it should be released with the `free'
354 call when it is no longer in use. If the list is empty,
355 the return value is `NULL'.
356 The function `tclistunshift' is used in order to add an element at the
358 top of a list object.
359 void tclistunshift(TCLIST *list, const void *ptr, int size);
361 `list' specifies the list object.
362 `ptr' specifies the pointer to the region of the new ele‐
363 ment.
364 `size' specifies the size of the region.
365 The function `tclistunshift2' is used in order to add a string element
367 at the top of a list object.
368 void tclistunshift2(TCLIST *list, const char *str);
370 `list' specifies the list object.
371 `str' specifies the string of the new element.
372 The function `tclistshift' is used in order to remove an element of the
374 top of a list object.
375 void *tclistshift(TCLIST *list, int *sp);
377 `list' specifies the list object.
378 `sp' specifies the pointer to the variable into which the
379 size of the region of the return value is assigned.
380 The return value is the pointer to the region of the
381 removed element.
382 Because an additional zero code is appended at the end of
383 the region of the return value, the return value can be
384 treated as a character string. Because the region of the
385 return value is allocated with the `malloc' call, it
386 should be released with the `free' call when it is no
387 longer in use. If the list is empty, the return value is
388 `NULL'.
389 The function `tclistshift2' is used in order to remove a string element
391 of the top of a list object.
392 char *tclistshift2(TCLIST *list);
394 `list' specifies the list object.
395 The return value is the string of the removed element.
396 Because the region of the return value is allocated with
397 the `malloc' call, it should be released with the `free'
398 call when it is no longer in use. If the list is empty,
399 the return value is `NULL'.
400 The function `tclistinsert' is used in order to add an element at the
402 specified location of a list object.
403 void tclistinsert(TCLIST *list, int index, const void *ptr, int
405 size);
406 `list' specifies the list object.
407 `index' specifies the index of the new element.
408 `ptr' specifies the pointer to the region of the new ele‐
409 ment.
410 `size' specifies the size of the region.
411 If `index' is equal to or more than the number of ele‐
412 ments, this function has no effect.
413 The function `tclistinsert2' is used in order to add a string element
415 at the specified location of a list object.
416 void tclistinsert2(TCLIST *list, int index, const char *str);
418 `list' specifies the list object.
419 `index' specifies the index of the new element.
420 `str' specifies the string of the new element.
421 If `index' is equal to or more than the number of ele‐
422 ments, this function has no effect.
423 The function `tclistremove' is used in order to remove an element at
425 the specified location of a list object.
426 void *tclistremove(TCLIST *list, int index, int *sp);
428 `list' specifies the list object.
429 `index' specifies the index of the element to be removed.
430 `sp' specifies the pointer to the variable into which the
431 size of the region of the return value is assigned.
432 The return value is the pointer to the region of the
433 removed element.
434 Because an additional zero code is appended at the end of
435 the region of the return value, the return value can be
436 treated as a character string. Because the region of the
437 return value is allocated with the `malloc' call, it
438 should be released with the `free' call when it is no
439 longer in use. If `index' is equal to or more than the
440 number of elements, no element is removed and the return
441 value is `NULL'.
442 The function `tclistremove2' is used in order to remove a string ele‐
444 ment at the specified location of a list object.
445 char *tclistremove2(TCLIST *list, int index);
447 `list' specifies the list object.
448 `index' specifies the index of the element to be removed.
449 The return value is the string of the removed element.
450 Because the region of the return value is allocated with
451 the `malloc' call, it should be released with the `free'
452 call when it is no longer in use. If `index' is equal to
453 or more than the number of elements, no element is
454 removed and the return value is `NULL'.
455 The function `tclistover' is used in order to overwrite an element at
457 the specified location of a list object.
458 void tclistover(TCLIST *list, int index, const void *ptr, int
460 size);
461 `list' specifies the list object.
462 `index' specifies the index of the element to be over‐
463 written.
464 `ptr' specifies the pointer to the region of the new con‐
465 tent.
466 `size' specifies the size of the new content.
467 If `index' is equal to or more than the number of ele‐
468 ments, this function has no effect.
469 The function `tclistover2' is used in order to overwrite a string ele‐
471 ment at the specified location of a list object.
472 void tclistover2(TCLIST *list, int index, const char *str);
474 `list' specifies the list object.
475 `index' specifies the index of the element to be over‐
476 written.
477 `str' specifies the string of the new content.
478 If `index' is equal to or more than the number of ele‐
479 ments, this function has no effect.
480 The function `tclistsort' is used in order to sort elements of a list
482 object in lexical order.
483 void tclistsort(TCLIST *list);
485 `list' specifies the list object.
486 The function `tclistlsearch' is used in order to search a list object
488 for an element using liner search.
489 int tclistlsearch(const TCLIST *list, const void *ptr, int
491 size);
492 `list' specifies the list object.
493 `ptr' specifies the pointer to the region of the key.
494 `size' specifies the size of the region.
495 The return value is the index of a corresponding element
496 or -1 if there is no corresponding element.
497 If two or more elements correspond, the former returns.
498 The function `tclistbsearch' is used in order to search a list object
500 for an element using binary search.
501 int tclistbsearch(const TCLIST *list, const void *ptr, int
503 size);
504 `list' specifies the list object. It should be sorted in
505 lexical order.
506 `ptr' specifies the pointer to the region of the key.
507 `size' specifies the size of the region.
508 The return value is the index of a corresponding element
509 or -1 if there is no corresponding element.
510 If two or more elements correspond, which returns is not
511 defined.
512 The function `tclistclear' is used in order to clear a list object.
514 void tclistclear(TCLIST *list);
516 `list' specifies the list object.
517 All elements are removed.
518 The function `tclistdump' is used in order to serialize a list object
520 into a byte array.
521 void *tclistdump(const TCLIST *list, int *sp);
523 `list' specifies the list object.
524 `sp' specifies the pointer to the variable into which the
525 size of the region of the return value is assigned.
526 The return value is the pointer to the region of the
527 result serial region.
528 Because the region of the return value is allocated with
529 the `malloc' call, it should be released with the `free'
530 call when it is no longer in use.
531 The function `tclistload' is used in order to create a list object from
533 a serialized byte array.
534 TCLIST *tclistload(const void *ptr, int size);
536 `ptr' specifies the pointer to the region of serialized
537 byte array.
538 `size' specifies the size of the region.
539 The return value is a new list object.
540 Because the object of the return value is created with
541 the function `tclistnew', it should be deleted with the
542 function `tclistdel' when it is no longer in use.
543
546 The function `tcmapnew' is used in order to create a map object.
547 TCMAP *tcmapnew(void);
549 The return value is the new map object.
550 The function `tcmapnew2' is used in order to create a map object with
552 specifying the number of the buckets.
553 TCMAP *tcmapnew2(uint32_t bnum);
555 `bnum' specifies the number of the buckets.
556 The return value is the new map object.
557 The function `tcmapnew3' is used in order to create a map object with
559 initial string elements.
560 TCMAP *tcmapnew3(const char *str, ...);
562 `str' specifies the string of the first element.
563 The other arguments are other elements. They should be
564 trailed by a `NULL' argument.
565 The return value is the new map object.
566 The key and the value of each record are situated one
567 after the other.
568 The function `tcmapdup' is used in order to copy a map object.
570 TCMAP *tcmapdup(const TCMAP *map);
572 `map' specifies the map object.
573 The return value is the new map object equivalent to the
574 specified object.
575 The function `tcmapdel' is used in order to delete a map object.
577 void tcmapdel(TCMAP *map);
579 `map' specifies the map object.
580 Note that the deleted object and its derivatives can not
581 be used anymore.
582 The function `tcmapput' is used in order to store a record into a map
584 object.
585 void tcmapput(TCMAP *map, const void *kbuf, int ksiz, const void
587 *vbuf, int vsiz);
588 `map' specifies the map object.
589 `kbuf' specifies the pointer to the region of the key.
590 `ksiz' specifies the size of the region of the key.
591 `vbuf' specifies the pointer to the region of the value.
592 `vsiz' specifies the size of the region of the value.
593 If a record with the same key exists in the map, it is
594 overwritten.
595 The function `tcmapput2' is used in order to store a string record into
597 a map object.
598 void tcmapput2(TCMAP *map, const char *kstr, const char *vstr);
600 `map' specifies the map object.
601 `kstr' specifies the string of the key.
602 `vstr' specifies the string of the value.
603 If a record with the same key exists in the map, it is
604 overwritten.
605 The function `tcmapputkeep' is used in order to store a new record into
607 a map object.
608 bool tcmapputkeep(TCMAP *map, const void *kbuf, int ksiz, const
610 void *vbuf, int vsiz);
611 `map' specifies the map object.
612 `kbuf' specifies the pointer to the region of the key.
613 `ksiz' specifies the size of the region of the key.
614 `vbuf' specifies the pointer to the region of the value.
615 `vsiz' specifies the size of the region of the value.
616 If successful, the return value is true, else, it is
617 false.
618 If a record with the same key exists in the map, this
619 function has no effect.
620 The function `tcmapputkeep2' is used in order to store a new string
622 record into a map object.
623 bool tcmapputkeep2(TCMAP *map, const char *kstr, const char
625 *vstr);
626 `map' specifies the map object.
627 `kstr' specifies the string of the key.
628 `vstr' specifies the string of the value.
629 If successful, the return value is true, else, it is
630 false.
631 If a record with the same key exists in the map, this
632 function has no effect.
633 The function `tcmapputcat' is used in order to concatenate a value at
635 the end of the value of the existing record in a map object.
636 void tcmapputcat(TCMAP *map, const void *kbuf, int ksiz, const
638 void *vbuf, int vsiz);
639 `map' specifies the map object.
640 `kbuf' specifies the pointer to the region of the key.
641 `ksiz' specifies the size of the region of the key.
642 `vbuf' specifies the pointer to the region of the value.
643 `vsiz' specifies the size of the region of the value.
644 If there is no corresponding record, a new record is cre‐
645 ated.
646 The function `tcmapputcat2' is used in order to concatenate a string
648 value at the end of the value of the existing record in a map object.
649 void tcmapputcat2(TCMAP *map, const char *kstr, const char
651 *vstr);
652 `map' specifies the map object.
653 `kstr' specifies the string of the key.
654 `vstr' specifies the string of the value.
655 If there is no corresponding record, a new record is cre‐
656 ated.
657 The function `tcmapout' is used in order to remove a record of a map
659 object.
660 bool tcmapout(TCMAP *map, const void *kbuf, int ksiz);
662 `map' specifies the map object.
663 `kbuf' specifies the pointer to the region of the key.
664 `ksiz' specifies the size of the region of the key.
665 If successful, the return value is true. False is
666 returned when no record corresponds to the specified key.
667 The function `tcmapout2' is used in order to remove a string record of
669 a map object.
670 bool tcmapout2(TCMAP *map, const char *kstr);
672 `map' specifies the map object.
673 `kstr' specifies the string of the key.
674 If successful, the return value is true. False is
675 returned when no record corresponds to the specified key.
676 The function `tcmapget' is used in order to retrieve a record in a map
678 object.
679 const void *tcmapget(const TCMAP *map, const void *kbuf, int
681 ksiz, int *sp);
682 `map' specifies the map object.
683 `kbuf' specifies the pointer to the region of the key.
684 `ksiz' specifies the size of the region of the key.
685 `sp' specifies the pointer to the variable into which the
686 size of the region of the return value is assigned.
687 If successful, the return value is the pointer to the
688 region of the value of the corresponding record. `NULL'
689 is returned when no record corresponds.
690 Because an additional zero code is appended at the end of
691 the region of the return value, the return value can be
692 treated as a character string.
693 The function `tcmapget2' is used in order to retrieve a string record
695 in a map object.
696 const char *tcmapget2(const TCMAP *map, const char *kstr);
698 `map' specifies the map object.
699 `kstr' specifies the string of the key.
700 If successful, the return value is the string of the
701 value of the corresponding record. `NULL' is returned
702 when no record corresponds.
703 The function `tcmapmove' is used in order to move a record to the edge
705 of a map object.
706 bool tcmapmove(TCMAP *map, const void *kbuf, int ksiz, bool
708 head);
709 `map' specifies the map object.
710 `kbuf' specifies the pointer to the region of a key.
711 `ksiz' specifies the size of the region of the key.
712 `head' specifies the destination which is the head if it
713 is true or the tail if else.
714 If successful, the return value is true. False is
715 returned when no record corresponds to the specified key.
716 The function `tcmapmove2' is used in order to move a string record to
718 the edge of a map object.
719 bool tcmapmove2(TCMAP *map, const char *kstr, bool head);
721 `map' specifies the map object.
722 `kstr' specifies the string of a key.
723 `head' specifies the destination which is the head if it
724 is true or the tail if else.
725 If successful, the return value is true. False is
726 returned when no record corresponds to the specified key.
727 The function `tcmapiterinit' is used in order to initialize the itera‐
729 tor of a map object.
730 void tcmapiterinit(TCMAP *map);
732 `map' specifies the map object.
733 The iterator is used in order to access the key of every
734 record stored in the map object.
735 The function `tcmapiternext' is used in order to get the next key of
737 the iterator of a map object.
738 const void *tcmapiternext(TCMAP *map, int *sp);
740 `map' specifies the map object.
741 `sp' specifies the pointer to the variable into which the
742 size of the region of the return value is assigned.
743 If successful, the return value is the pointer to the
744 region of the next key, else, it is `NULL'. `NULL' is
745 returned when no record can be fetched from the iterator.
746 Because an additional zero code is appended at the end of
747 the region of the return value, the return value can be
748 treated as a character string. The order of iteration is
749 assured to be the same as the stored order.
750 The function `tcmapiternext2' is used in order to get the next key
752 string of the iterator of a map object.
753 const char *tcmapiternext2(TCMAP *map);
755 `map' specifies the map object.
756 If successful, the return value is the pointer to the
757 region of the next key, else, it is `NULL'. `NULL' is
758 returned when no record can be fetched from the iterator.
759 The order of iteration is assured to be the same as the
760 stored order.
761 The function `tcmaprnum' is used in order to get the number of records
763 stored in a map object.
764 uint64_t tcmaprnum(const TCMAP *map);
766 `map' specifies the map object.
767 The return value is the number of the records stored in
768 the map object.
769 The function `tcmapmsiz' is used in order to get the total size of mem‐
771 ory used in a map object.
772 uint64_t tcmapmsiz(const TCMAP *map);
774 `map' specifies the map object.
775 The return value is the total size of memory used in a
776 map object.
777 The function `tcmapkeys' is used in order to create a list object con‐
779 taining all keys in a map object.
780 TCLIST *tcmapkeys(const TCMAP *map);
782 `map' specifies the map object.
783 The return value is the new list object containing all
784 keys in the map object.
785 Because the object of the return value is created with
786 the function `tclistnew', it should be deleted with the
787 function `tclistdel' when it is no longer in use.
788 The function `tcmapvals' is used in order to create a list object con‐
790 taining all values in a map object.
791 TCLIST *tcmapvals(const TCMAP *map);
793 `map' specifies the map object.
794 The return value is the new list object containing all
795 values in the map object.
796 Because the object of the return value is created with
797 the function `tclistnew', it should be deleted with the
798 function `tclistdel' when it is no longer in use.
799 The function `tcmapaddint' is used in order to add an integer to a
801 record in a map object.
802 int tcmapaddint(TCMAP *map, const void *kbuf, int ksiz, int
804 num);
805 `map' specifies the map object.
806 `kbuf' specifies the pointer to the region of the key.
807 `ksiz' specifies the size of the region of the key.
808 `num' specifies the additional value.
809 The return value is the summation value.
810 If the corresponding record exists, the value is treated
811 as an integer and is added to. If no record corresponds,
812 a new record of the additional value is stored.
813 The function `tcmapadddouble' is used in order to add a real number to
815 a record in a map object.
816 double tcmapadddouble(TCMAP *map, const void *kbuf, int ksiz,
818 double num);
819 `map' specifies the map object.
820 `kbuf' specifies the pointer to the region of the key.
821 `ksiz' specifies the size of the region of the key.
822 `num' specifies the additional value.
823 The return value is the summation value.
824 If the corresponding record exists, the value is treated
825 as a real number and is added to. If no record corre‐
826 sponds, a new record of the additional value is stored.
827 The function `tcmapclear' is used in order to clear a map object.
829 void tcmapclear(TCMAP *map);
831 `map' specifies the map object.
832 All records are removed.
833 The function `tcmapcutfront' is used in order to remove front records
835 of a map object.
836 void tcmapcutfront(TCMAP *map, int num);
838 `map' specifies the map object.
839 `num' specifies the number of records to be removed.
840 The function `tcmapdump' is used in order to serialize a map object
842 into a byte array.
843 void *tcmapdump(const TCMAP *map, int *sp);
845 `map' specifies the map object.
846 `sp' specifies the pointer to the variable into which the
847 size of the region of the return value is assigned.
848 The return value is the pointer to the region of the
849 result serial region.
850 Because the region of the return value is allocated with
851 the `malloc' call, it should be released with the `free'
852 call when it is no longer in use.
853 The function `tcmapload' is used in order to create a map object from a
855 serialized byte array.
856 TCMAP *tcmapload(const void *ptr, int size);
858 `ptr' specifies the pointer to the region of serialized
859 byte array.
860 `size' specifies the size of the region.
861 The return value is a new map object.
862 Because the object of the return value is created with
863 the function `tcmapnew', it should be deleted with the
864 function `tcmapdel' when it is no longer in use.
865
868 The function `tctreenew' is used in order to create a tree object.
869 TCTREE *tctreenew(void);
871 The return value is the new tree object.
872 The function `tctreenew2' is used in order to create a tree object with
874 specifying the custom comparison function.
875 TCTREE *tctreenew2(TCCMP cmp, void *cmpop);
877 `cmp' specifies the pointer to the custom comparison
878 function. It receives five parameters. The first param‐
879 eter is the pointer to the region of one key. The second
880 parameter is the size of the region of one key. The
881 third parameter is the pointer to the region of the other
882 key. The fourth parameter is the size of the region of
883 the other key. The fifth parameter is the pointer to the
884 optional opaque object. It returns positive if the for‐
885 mer is big, negative if the latter is big, 0 if both are
886 equivalent.
887 `cmpop' specifies an arbitrary pointer to be given as a
888 parameter of the comparison function. If it is not
889 needed, `NULL' can be specified.
890 The return value is the new tree object.
891 The default comparison function compares keys of two
892 records by lexical order. The functions `tccmplexical'
893 (dafault), `tccmpdecimal', `tccmpint32', and `tccmpint64'
894 are built-in.
895 The function `tctreedup' is used in order to copy a tree object.
897 TCTREE *tctreedup(const TCTREE *tree);
899 `tree' specifies the tree object.
900 The return value is the new tree object equivalent to the
901 specified object.
902 The function `tctreedel' is used in order to delete a tree object.
904 void tctreedel(TCTREE *tree);
906 `tree' specifies the tree object.
907 Note that the deleted object and its derivatives can not
908 be used anymore.
909 The function `tctreeput' is used in order to store a record into a tree
911 object.
912 void tctreeput(TCTREE *tree, const void *kbuf, int ksiz, const
914 void *vbuf, int vsiz);
915 `tree' specifies the tree object.
916 `kbuf' specifies the pointer to the region of the key.
917 `ksiz' specifies the size of the region of the key.
918 `vbuf' specifies the pointer to the region of the value.
919 `vsiz' specifies the size of the region of the value.
920 If a record with the same key exists in the tree, it is
921 overwritten.
922 The function `tctreeput2' is used in order to store a string record
924 into a tree object.
925 void tctreeput2(TCTREE *tree, const char *kstr, const char
927 *vstr);
928 `tree' specifies the tree object.
929 `kstr' specifies the string of the key.
930 `vstr' specifies the string of the value.
931 If a record with the same key exists in the tree, it is
932 overwritten.
933 The function `tctreeputkeep' is used in order to store a new record
935 into a tree object.
936 bool tctreeputkeep(TCTREE *tree, const void *kbuf, int ksiz,
938 const void *vbuf, int vsiz);
939 `tree' specifies the tree object.
940 `kbuf' specifies the pointer to the region of the key.
941 `ksiz' specifies the size of the region of the key.
942 `vbuf' specifies the pointer to the region of the value.
943 `vsiz' specifies the size of the region of the value.
944 If successful, the return value is true, else, it is
945 false.
946 If a record with the same key exists in the tree, this
947 function has no effect.
948 The function `tctreeputkeep2' is used in order to store a new string
950 record into a tree object.
951 bool tctreeputkeep2(TCTREE *tree, const char *kstr, const char
953 *vstr);
954 `tree' specifies the tree object.
955 `kstr' specifies the string of the key.
956 `vstr' specifies the string of the value.
957 If successful, the return value is true, else, it is
958 false.
959 If a record with the same key exists in the tree, this
960 function has no effect.
961 The function `tctreeputcat' is used in order to concatenate a value at
963 the end of the value of the existing record in a tree object.
964 void tctreeputcat(TCTREE *tree, const void *kbuf, int ksiz,
966 const void *vbuf, int vsiz);
967 `tree' specifies the tree object.
968 `kbuf' specifies the pointer to the region of the key.
969 `ksiz' specifies the size of the region of the key.
970 `vbuf' specifies the pointer to the region of the value.
971 `vsiz' specifies the size of the region of the value.
972 If there is no corresponding record, a new record is cre‐
973 ated.
974 The function `tctreeputcat2' is used in order to concatenate a string
976 value at the end of the value of the existing record in a tree object.
977 void tctreeputcat2(TCTREE *tree, const char *kstr, const char
979 *vstr);
980 `tree' specifies the tree object.
981 `kstr' specifies the string of the key.
982 `vstr' specifies the string of the value.
983 If there is no corresponding record, a new record is cre‐
984 ated.
985 The function `tctreeout' is used in order to remove a record of a tree
987 object.
988 bool tctreeout(TCTREE *tree, const void *kbuf, int ksiz);
990 `tree' specifies the tree object.
991 `kbuf' specifies the pointer to the region of the key.
992 `ksiz' specifies the size of the region of the key.
993 If successful, the return value is true. False is
994 returned when no record corresponds to the specified key.
995 The function `tctreeout2' is used in order to remove a string record of
997 a tree object.
998 bool tctreeout2(TCTREE *tree, const char *kstr);
1000 `tree' specifies the tree object.
1001 `kstr' specifies the string of the key.
1002 If successful, the return value is true. False is
1003 returned when no record corresponds to the specified key.
1004 The function `tctreeget' is used in order to retrieve a record in a
1006 tree object.
1007 const void *tctreeget(TCTREE *tree, const void *kbuf, int ksiz,
1009 int *sp);
1010 `tree' specifies the tree object.
1011 `kbuf' specifies the pointer to the region of the key.
1012 `ksiz' specifies the size of the region of the key.
1013 `sp' specifies the pointer to the variable into which the
1014 size of the region of the return value is assigned.
1015 If successful, the return value is the pointer to the
1016 region of the value of the corresponding record. `NULL'
1017 is returned when no record corresponds.
1018 Because an additional zero code is appended at the end of
1019 the region of the return value, the return value can be
1020 treated as a character string.
1021 The function `tctreeget2' is used in order to retrieve a string record
1023 in a tree object.
1024 const char *tctreeget2(TCTREE *tree, const char *kstr);
1026 `tree' specifies the tree object.
1027 `kstr' specifies the string of the key.
1028 If successful, the return value is the string of the
1029 value of the corresponding record. `NULL' is returned
1030 when no record corresponds.
1031 The function `tctreeiterinit' is used in order to initialize the itera‐
1033 tor of a tree object.
1034 void tctreeiterinit(TCTREE *tree);
1036 `tree' specifies the tree object.
1037 The iterator is used in order to access the key of every
1038 record stored in the tree object.
1039 The function `tctreeiternext' is used in order to get the next key of
1041 the iterator of a tree object.
1042 const void *tctreeiternext(TCTREE *tree, int *sp);
1044 `tree' specifies the tree object.
1045 `sp' specifies the pointer to the variable into which the
1046 size of the region of the return value is assigned.
1047 If successful, the return value is the pointer to the
1048 region of the next key, else, it is `NULL'. `NULL' is
1049 returned when no record can be fetched from the iterator.
1050 Because an additional zero code is appended at the end of
1051 the region of the return value, the return value can be
1052 treated as a character string. The order of iteration is
1053 assured to be ascending of the keys.
1054 The function `tctreeiternext2' is used in order to get the next key
1056 string of the iterator of a tree object.
1057 const char *tctreeiternext2(TCTREE *tree);
1059 `tree' specifies the tree object.
1060 If successful, the return value is the pointer to the
1061 region of the next key, else, it is `NULL'. `NULL' is
1062 returned when no record can be fetched from the iterator.
1063 The order of iteration is assured to be ascending of the
1064 keys.
1065 The function `tctreernum' is used in order to get the number of records
1067 stored in a tree object.
1068 uint64_t tctreernum(const TCTREE *tree);
1070 `tree' specifies the tree object.
1071 The return value is the number of the records stored in
1072 the tree object.
1073 The function `tctreemsiz' is used in order to get the total size of
1075 memory used in a tree object.
1076 uint64_t tctreemsiz(const TCTREE *tree);
1078 `tree' specifies the tree object.
1079 The return value is the total size of memory used in a
1080 tree object.
1081 The function `tctreekeys' is used in order to create a list object con‐
1083 taining all keys in a tree object.
1084 TCLIST *tctreekeys(const TCTREE *tree);
1086 `tree' specifies the tree object.
1087 The return value is the new list object containing all
1088 keys in the tree object.
1089 Because the object of the return value is created with
1090 the function `tclistnew', it should be deleted with the
1091 function `tclistdel' when it is no longer in use.
1092 The function `tctreevals' is used in order to create a list object con‐
1094 taining all values in a tree object.
1095 TCLIST *tctreevals(const TCTREE *tree);
1097 `tree' specifies the tree object.
1098 The return value is the new list object containing all
1099 values in the tree object.
1100 Because the object of the return value is created with
1101 the function `tclistnew', it should be deleted with the
1102 function `tclistdel' when it is no longer in use.
1103 The function `tctreeaddint' is used in order to add an integer to a
1105 record in a tree object.
1106 int tctreeaddint(TCTREE *tree, const void *kbuf, int ksiz, int
1108 num);
1109 `tree' specifies the tree object.
1110 `kbuf' specifies the pointer to the region of the key.
1111 `ksiz' specifies the size of the region of the key.
1112 `num' specifies the additional value.
1113 The return value is the summation value.
1114 If the corresponding record exists, the value is treated
1115 as an integer and is added to. If no record corresponds,
1116 a new record of the additional value is stored.
1117 The function `tctreeadddouble' is used in order to add a real number to
1119 a record in a tree object.
1120 double tctreeadddouble(TCTREE *tree, const void *kbuf, int ksiz,
1122 double num);
1123 `tree' specifies the tree object.
1124 `kbuf' specifies the pointer to the region of the key.
1125 `ksiz' specifies the size of the region of the key.
1126 `num' specifies the additional value.
1127 The return value is the summation value.
1128 If the corresponding record exists, the value is treated
1129 as a real number and is added to. If no record corre‐
1130 sponds, a new record of the additional value is stored.
1131 The function `tctreeclear' is used in order to clear a tree object.
1133 void tctreeclear(TCTREE *tree);
1135 `tree' specifies the tree object.
1136 All records are removed.
1137 The function `tctreecutfringe' is used in order to remove fringe
1139 records of a tree object.
1140 void tctreecutfringe(TCTREE *tree, int num);
1142 `tree' specifies the tree object.
1143 `num' specifies the number of records to be removed.
1144 The function `tctreedump' is used in order to serialize a tree object
1146 into a byte array.
1147 void *tctreedump(const TCTREE *tree, int *sp);
1149 `tree' specifies the tree object.
1150 `sp' specifies the pointer to the variable into which the
1151 size of the region of the return value is assigned.
1152 The return value is the pointer to the region of the
1153 result serial region.
1154 Because the region of the return value is allocated with
1155 the `malloc' call, it should be released with the `free'
1156 call when it is no longer in use.
1157 The function `tctreeload' is used in order to create a tree object from
1159 a serialized byte array.
1160 TCTREE *tctreeload(const void *ptr, int size, TCCMP cmp, void
1162 *cmpop);
1163 `ptr' specifies the pointer to the region of serialized
1164 byte array.
1165 `size' specifies the size of the region.
1166 `cmp' specifies the pointer to the custom comparison
1167 function.
1168 `cmpop' specifies an arbitrary pointer to be given as a
1169 parameter of the comparison function.
1170 If it is not needed, `NULL' can be specified.
1171 The return value is a new tree object.
1172 Because the object of the return value is created with
1173 the function `tctreenew', it should be deleted with the
1174 function `tctreedel' when it is no longer in use.
1175
1178 The function `tcmdbnew' is used in order to create an on-memory hash
1179 database object.
1180 TCMDB *tcmdbnew(void);
1182 The return value is the new on-memory hash database
1183 object.
1184 The object can be shared by plural threads because of the
1185 internal mutex.
1186 The function `tcmdbnew2' is used in order to create an on-memory hash
1188 database object with specifying the number of the buckets.
1189 TCMDB *tcmdbnew2(uint32_t bnum);
1191 `bnum' specifies the number of the buckets.
1192 The return value is the new on-memory hash database
1193 object.
1194 The object can be shared by plural threads because of the
1195 internal mutex.
1196 The function `tcmdbdel' is used in order to delete an on-memory hash
1198 database object.
1199 void tcmdbdel(TCMDB *mdb);
1201 `mdb' specifies the on-memory hash database object.
1202 The function `tcmdbput' is used in order to store a record into an
1204 on-memory hash database object.
1205 void tcmdbput(TCMDB *mdb, const void *kbuf, int ksiz, const void
1207 *vbuf, int vsiz);
1208 `mdb' specifies the on-memory hash database object.
1209 `kbuf' specifies the pointer to the region of the key.
1210 `ksiz' specifies the size of the region of the key.
1211 `vbuf' specifies the pointer to the region of the value.
1212 `vsiz' specifies the size of the region of the value.
1213 If a record with the same key exists in the database, it
1214 is overwritten.
1215 The function `tcmdbput2' is used in order to store a string record into
1217 an on-memory hash database object.
1218 void tcmdbput2(TCMDB *mdb, const char *kstr, const char *vstr);
1220 `mdb' specifies the on-memory hash database object.
1221 `kstr' specifies the string of the key.
1222 `vstr' specifies the string of the value.
1223 If a record with the same key exists in the database, it
1224 is overwritten.
1225 The function `tcmdbputkeep' is used in order to store a new record into
1227 an on-memory hash database object.
1228 bool tcmdbputkeep(TCMDB *mdb, const void *kbuf, int ksiz, const
1230 void *vbuf, int vsiz);
1231 `mdb' specifies the on-memory hash database object.
1232 `kbuf' specifies the pointer to the region of the key.
1233 `ksiz' specifies the size of the region of the key.
1234 `vbuf' specifies the pointer to the region of the value.
1235 `vsiz' specifies the size of the region of the value.
1236 If successful, the return value is true, else, it is
1237 false.
1238 If a record with the same key exists in the database,
1239 this function has no effect.
1240 The function `tcmdbputkeep2' is used in order to store a new string
1242 record into an on-memory hash database object.
1243 bool tcmdbputkeep2(TCMDB *mdb, const char *kstr, const char
1245 *vstr);
1246 `mdb' specifies the on-memory hash database object.
1247 `kstr' specifies the string of the key.
1248 `vstr' specifies the string of the value.
1249 If successful, the return value is true, else, it is
1250 false.
1251 If a record with the same key exists in the database,
1252 this function has no effect.
1253 The function `tcmdbputcat' is used in order to concatenate a value at
1255 the end of the existing record in an on-memory hash database.
1256 void tcmdbputcat(TCMDB *mdb, const void *kbuf, int ksiz, const
1258 void *vbuf, int vsiz);
1259 `mdb' specifies the on-memory hash database object.
1260 `kbuf' specifies the pointer to the region of the key.
1261 `ksiz' specifies the size of the region of the key.
1262 `vbuf' specifies the pointer to the region of the value.
1263 `vsiz' specifies the size of the region of the value.
1264 If there is no corresponding record, a new record is cre‐
1265 ated.
1266 The function `tcmdbputcat2' is used in order to concatenate a string at
1268 the end of the existing record in an on-memory hash database.
1269 void tcmdbputcat2(TCMDB *mdb, const char *kstr, const char
1271 *vstr);
1272 `mdb' specifies the on-memory hash database object.
1273 `kstr' specifies the string of the key.
1274 `vstr' specifies the string of the value.
1275 If there is no corresponding record, a new record is cre‐
1276 ated.
1277 The function `tcmdbout' is used in order to remove a record of an
1279 on-memory hash database object.
1280 bool tcmdbout(TCMDB *mdb, const void *kbuf, int ksiz);
1282 `mdb' specifies the on-memory hash database object.
1283 `kbuf' specifies the pointer to the region of the key.
1284 `ksiz' specifies the size of the region of the key.
1285 If successful, the return value is true. False is
1286 returned when no record corresponds to the specified key.
1287 The function `tcmdbout2' is used in order to remove a string record of
1289 an on-memory hash database object.
1290 bool tcmdbout2(TCMDB *mdb, const char *kstr);
1292 `mdb' specifies the on-memory hash database object.
1293 `kstr' specifies the string of the key.
1294 If successful, the return value is true. False is
1295 returned when no record corresponds to the specified key.
1296 The function `tcmdbget' is used in order to retrieve a record in an
1298 on-memory hash database object.
1299 void *tcmdbget(TCMDB *mdb, const void *kbuf, int ksiz, int *sp);
1301 `mdb' specifies the on-memory hash database object.
1302 `kbuf' specifies the pointer to the region of the key.
1303 `ksiz' specifies the size of the region of the key.
1304 `sp' specifies the pointer to the variable into which the
1305 size of the region of the return value is assigned.
1306 If successful, the return value is the pointer to the
1307 region of the value of the corresponding record. `NULL'
1308 is returned when no record corresponds.
1309 Because an additional zero code is appended at the end of
1310 the region of the return value, the return value can be
1311 treated as a character string. Because the region of the
1312 return value is allocated with the `malloc' call, it
1313 should be released with the `free' call when it is no
1314 longer in use.
1315 The function `tcmdbget2' is used in order to retrieve a string record
1317 in an on-memory hash database object.
1318 char *tcmdbget2(TCMDB *mdb, const char *kstr);
1320 `mdb' specifies the on-memory hash database object.
1321 `kstr' specifies the string of the key.
1322 If successful, the return value is the string of the
1323 value of the corresponding record. `NULL' is returned
1324 when no record corresponds.
1325 Because the region of the return value is allocated with
1326 the `malloc' call, it should be released with the `free'
1327 call when it is no longer in use.
1328 The function `tcmdbvsiz' is used in order to get the size of the value
1330 of a record in an on-memory hash database object.
1331 int tcmdbvsiz(TCMDB *mdb, const void *kbuf, int ksiz);
1333 `mdb' specifies the on-memory hash database object.
1334 `kbuf' specifies the pointer to the region of the key.
1335 `ksiz' specifies the size of the region of the key.
1336 If successful, the return value is the size of the value
1337 of the corresponding record, else, it is -1.
1338 The function `tcmdbvsiz2' is used in order to get the size of the value
1340 of a string record in an on-memory hash database object.
1341 int tcmdbvsiz2(TCMDB *mdb, const char *kstr);
1343 `mdb' specifies the on-memory hash database object.
1344 `kstr' specifies the string of the key.
1345 If successful, the return value is the size of the value
1346 of the corresponding record, else, it is -1.
1347 The function `tcmdbiterinit' is used in order to initialize the itera‐
1349 tor of an on-memory hash database object.
1350 void tcmdbiterinit(TCMDB *mdb);
1352 `mdb' specifies the on-memory hash database object.
1353 The iterator is used in order to access the key of every
1354 record stored in the on-memory hash database.
1355 The function `tcmdbiternext' is used in order to get the next key of
1357 the iterator of an on-memory hash database object.
1358 void *tcmdbiternext(TCMDB *mdb, int *sp);
1360 `mdb' specifies the on-memory hash database object.
1361 `sp' specifies the pointer to the variable into which the
1362 size of the region of the return
1363 value is assigned.
1364 If successful, the return value is the pointer to the
1365 region of the next key, else, it is `NULL'. `NULL' is
1366 returned when no record can be fetched from the iterator.
1367 Because an additional zero code is appended at the end of
1368 the region of the return value, the return value can be
1369 treated as a character string. Because the region of the
1370 return value is allocated with the `malloc' call, it
1371 should be released with the `free' call when it is no
1372 longer in use. The order of iteration is assured to be
1373 the same as the stored order.
1374 The function `tcmdbiternext2' is used in order to get the next key
1376 string of the iterator of an on-memory hash database object.
1377 char *tcmdbiternext2(TCMDB *mdb);
1379 `mdb' specifies the on-memory hash database object.
1380 If successful, the return value is the pointer to the
1381 region of the next key, else, it is `NULL'. `NULL' is
1382 returned when no record can be fetched from the iterator.
1383 Because the region of the return value is allocated with
1384 the `malloc' call, it should be released with the `free'
1385 call when it is no longer in use. The order of iteration
1386 is assured to be the same as the stored order.
1387 The function `tcmdbfwmkeys' is used in order to get forward matching
1389 keys in an on-memory hash database object.
1390 TCLIST *tcmdbfwmkeys(TCMDB *mdb, const void *pbuf, int psiz, int
1392 max);
1393 `mdb' specifies the on-memory hash database object.
1394 `pbuf' specifies the pointer to the region of the prefix.
1395 `psiz' specifies the size of the region of the prefix.
1396 `max' specifies the maximum number of keys to be fetched.
1397 If it is negative, no limit is specified.
1398 The return value is a list object of the corresponding
1399 keys. This function does never fail. It returns an
1400 empty list even if no key corresponds.
1401 Because the object of the return value is created with
1402 the function `tclistnew', it should be deleted with the
1403 function `tclistdel' when it is no longer in use. Note
1404 that this function may be very slow because every key in
1405 the database is scanned.
1406 The function `tcmdbfwmkeys2' is used in order to get forward matching
1408 string keys in an on-memory hash database object.
1409 TCLIST *tcmdbfwmkeys2(TCMDB *mdb, const char *pstr, int max);
1411 `mdb' specifies the on-memory hash database object.
1412 `pstr' specifies the string of the prefix.
1413 `max' specifies the maximum number of keys to be fetched.
1414 If it is negative, no limit is specified.
1415 The return value is a list object of the corresponding
1416 keys. This function does never fail. It returns an
1417 empty list even if no key corresponds.
1418 Because the object of the return value is created with
1419 the function `tclistnew', it should be deleted with the
1420 function `tclistdel' when it is no longer in use. Note
1421 that this function may be very slow because every key in
1422 the database is scanned.
1423 The function `tcmdbrnum' is used in order to get the number of records
1425 stored in an on-memory hash database object.
1426 uint64_t tcmdbrnum(TCMDB *mdb);
1428 `mdb' specifies the on-memory hash database object.
1429 The return value is the number of the records stored in
1430 the database.
1431 The function `tcmdbmsiz' is used in order to get the total size of mem‐
1433 ory used in an on-memory hash database object.
1434 uint64_t tcmdbmsiz(TCMDB *mdb);
1436 `mdb' specifies the on-memory hash database object.
1437 The return value is the total size of memory used in the
1438 database.
1439 The function `tcmdbaddint' is used in order to add an integer to a
1441 record in an on-memory hash database object.
1442 int tcmdbaddint(TCMDB *mdb, const void *kbuf, int ksiz, int
1444 num);
1445 `mdb' specifies the on-memory hash database object.
1446 `kbuf' specifies the pointer to the region of the key.
1447 `ksiz' specifies the size of the region of the key.
1448 `num' specifies the additional value.
1449 The return value is the summation value.
1450 If the corresponding record exists, the value is treated
1451 as an integer and is added to. If no record corresponds,
1452 a new record of the additional value is stored.
1453 The function `tcmdbadddouble' is used in order to add a real number to
1455 a record in an on-memory hash database object.
1456 double tcmdbadddouble(TCMDB *mdb, const void *kbuf, int ksiz,
1458 double num);
1459 `mdb' specifies the on-memory hash database object.
1460 `kbuf' specifies the pointer to the region of the key.
1461 `ksiz' specifies the size of the region of the key.
1462 `num' specifies the additional value.
1463 The return value is the summation value.
1464 If the corresponding record exists, the value is treated
1465 as a real number and is added to. If no record corre‐
1466 sponds, a new record of the additional value is stored.
1467 The function `tcmdbvanish' is used in order to clear an on-memory hash
1469 database object.
1470 void tcmdbvanish(TCMDB *mdb);
1472 `mdb' specifies the on-memory hash database object.
1473 All records are removed.
1474 The function `tcmdbcutfront' is used in order to remove front records
1476 of an on-memory hash database object.
1477 void tcmdbcutfront(TCMDB *mdb, int num);
1479 `mdb' specifies the on-memory hash database object.
1480 `num' specifies the number of records to be removed.
1481
1484 The function `tcndbnew' is used in order to create an on-memory tree
1485 database object.
1486 TCNDB *tcndbnew(void);
1488 The return value is the new on-memory tree database
1489 object.
1490 The object can be shared by plural threads because of the
1491 internal mutex.
1492 The function `tcndbnew2' is used in order to create an on-memory tree
1494 database object with specifying the custom comparison function.
1495 TCNDB *tcndbnew2(TCCMP cmp, void *cmpop);
1497 `cmp' specifies the pointer to the custom comparison
1498 function.
1499 `cmpop' specifies an arbitrary pointer to be given as a
1500 parameter of the comparison function. If it is not
1501 needed, `NULL' can be specified.
1502 The return value is the new on-memory tree database
1503 object.
1504 The default comparison function compares keys of two
1505 records by lexical order. The functions `tccmplexical'
1506 (dafault), `tccmpdecimal', `tccmpint32', and `tccmpint64'
1507 are built-in. The object can be shared by plural threads
1508 because of the internal mutex.
1509 The function `tcndbdel' is used in order to delete an on-memory tree
1511 database object.
1512 void tcndbdel(TCNDB *ndb);
1514 `ndb' specifies the on-memory tree database object.
1515 The function `tcndbput' is used in order to store a record into an
1517 on-memory tree database object.
1518 void tcndbput(TCNDB *ndb, const void *kbuf, int ksiz, const void
1520 *vbuf, int vsiz);
1521 `ndb' specifies the on-memory tree database object.
1522 `kbuf' specifies the pointer to the region of the key.
1523 `ksiz' specifies the size of the region of the key.
1524 `vbuf' specifies the pointer to the region of the value.
1525 `vsiz' specifies the size of the region of the value.
1526 If a record with the same key exists in the database, it
1527 is overwritten.
1528 The function `tcndbput2' is used in order to store a string record into
1530 an on-memory tree database object.
1531 void tcndbput2(TCNDB *ndb, const char *kstr, const char *vstr);
1533 `ndb' specifies the on-memory tree database object.
1534 `kstr' specifies the string of the key.
1535 `vstr' specifies the string of the value.
1536 If a record with the same key exists in the database, it
1537 is overwritten.
1538 The function `tcndbputkeep' is used in order to store a new record into
1540 an on-memory tree database object.
1541 bool tcndbputkeep(TCNDB *ndb, const void *kbuf, int ksiz, const
1543 void *vbuf, int vsiz);
1544 `ndb' specifies the on-memory tree database object.
1545 `kbuf' specifies the pointer to the region of the key.
1546 `ksiz' specifies the size of the region of the key.
1547 `vbuf' specifies the pointer to the region of the value.
1548 `vsiz' specifies the size of the region of the value.
1549 If successful, the return value is true, else, it is
1550 false.
1551 If a record with the same key exists in the database,
1552 this function has no effect.
1553 The function `tcndbputkeep2' is used in order to store a new string
1555 record into an on-memory tree database object.
1556 bool tcndbputkeep2(TCNDB *ndb, const char *kstr, const char
1558 *vstr);
1559 `ndb' specifies the on-memory tree database object.
1560 `kstr' specifies the string of the key.
1561 `vstr' specifies the string of the value.
1562 If successful, the return value is true, else, it is
1563 false.
1564 If a record with the same key exists in the database,
1565 this function has no effect.
1566 The function `tcndbputcat' is used in order to concatenate a value at
1568 the end of the existing record in an on-memory tree database.
1569 void tcndbputcat(TCNDB *ndb, const void *kbuf, int ksiz, const
1571 void *vbuf, int vsiz);
1572 `ndb' specifies the on-memory tree database object.
1573 `kbuf' specifies the pointer to the region of the key.
1574 `ksiz' specifies the size of the region of the key.
1575 `vbuf' specifies the pointer to the region of the value.
1576 `vsiz' specifies the size of the region of the value.
1577 If there is no corresponding record, a new record is cre‐
1578 ated.
1579 The function `tcndbputcat2' is used in order to concatenate a string at
1581 the end of the existing record in an on-memory tree database.
1582 void tcndbputcat2(TCNDB *ndb, const char *kstr, const char
1584 *vstr);
1585 `ndb' specifies the on-memory tree database object.
1586 `kstr' specifies the string of the key.
1587 `vstr' specifies the string of the value.
1588 If there is no corresponding record, a new record is cre‐
1589 ated.
1590 The function `tcndbout' is used in order to remove a record of an
1592 on-memory tree database object.
1593 bool tcndbout(TCNDB *ndb, const void *kbuf, int ksiz);
1595 `ndb' specifies the on-memory tree database object.
1596 `kbuf' specifies the pointer to the region of the key.
1597 `ksiz' specifies the size of the region of the key.
1598 If successful, the return value is true. False is
1599 returned when no record corresponds to the specified key.
1600 The function `tcndbout2' is used in order to remove a string record of
1602 an on-memory tree database object.
1603 bool tcndbout2(TCNDB *ndb, const char *kstr);
1605 `ndb' specifies the on-memory tree database object.
1606 `kstr' specifies the string of the key.
1607 If successful, the return value is true. False is
1608 returned when no record corresponds to the specified key.
1609 The function `tcndbget' is used in order to retrieve a record in an
1611 on-memory tree database object.
1612 void *tcndbget(TCNDB *ndb, const void *kbuf, int ksiz, int *sp);
1614 `ndb' specifies the on-memory tree database object.
1615 `kbuf' specifies the pointer to the region of the key.
1616 `ksiz' specifies the size of the region of the key.
1617 `sp' specifies the pointer to the variable into which the
1618 size of the region of the return value is assigned.
1619 If successful, the return value is the pointer to the
1620 region of the value of the corresponding record. `NULL'
1621 is returned when no record corresponds.
1622 Because an additional zero code is appended at the end of
1623 the region of the return value, the return value can be
1624 treated as a character string. Because the region of the
1625 return value is allocated with the `malloc' call, it
1626 should be released with the `free' call when it is no
1627 longer in use.
1628 The function `tcndbget2' is used in order to retrieve a string record
1630 in an on-memory tree database object.
1631 char *tcndbget2(TCNDB *ndb, const char *kstr);
1633 `ndb' specifies the on-memory tree database object.
1634 `kstr' specifies the string of the key.
1635 If successful, the return value is the string of the
1636 value of the corresponding record. `NULL' is returned
1637 when no record corresponds.
1638 Because the region of the return value is allocated with
1639 the `malloc' call, it should be released with the `free'
1640 call when it is no longer in use.
1641 The function `tcndbvsiz' is used in order to get the size of the value
1643 of a record in an on-memory tree database object.
1644 int tcndbvsiz(TCNDB *ndb, const void *kbuf, int ksiz);
1646 `ndb' specifies the on-memory tree database object.
1647 `kbuf' specifies the pointer to the region of the key.
1648 `ksiz' specifies the size of the region of the key.
1649 If successful, the return value is the size of the value
1650 of the corresponding record, else, it is -1.
1651 The function `tcndbvsiz2' is used in order to get the size of the value
1653 of a string record in an on-memory tree database object.
1654 int tcndbvsiz2(TCNDB *ndb, const char *kstr);
1656 `ndb' specifies the on-memory tree database object.
1657 `kstr' specifies the string of the key.
1658 If successful, the return value is the size of the value
1659 of the corresponding record, else, it is -1.
1660 The function `tcndbiterinit' is used in order to initialize the itera‐
1662 tor of an on-memory tree database object.
1663 void tcndbiterinit(TCNDB *ndb);
1665 `ndb' specifies the on-memory tree database object.
1666 The iterator is used in order to access the key of every
1667 record stored in the on-memory database.
1668 The function `tcndbiternext' is used in order to get the next key of
1670 the iterator of an on-memory tree database object.
1671 void *tcndbiternext(TCNDB *ndb, int *sp);
1673 `ndb' specifies the on-memory tree database object.
1674 `sp' specifies the pointer to the variable into which the
1675 size of the region of the return value is assigned.
1676 If successful, the return value is the pointer to the
1677 region of the next key, else, it is `NULL'. `NULL' is
1678 returned when no record can be fetched from the iterator.
1679 Because an additional zero code is appended at the end of
1680 the region of the return value, the return value can be
1681 treated as a character string. Because the region of the
1682 return value is allocated with the `malloc' call, it
1683 should be released with the `free' call when it is no
1684 longer in use. The order of iteration is assured to be
1685 the same as the stored order.
1686 The function `tcndbiternext2' is used in order to get the next key
1688 string of the iterator of an on-memory tree database object.
1689 char *tcndbiternext2(TCNDB *ndb);
1691 `ndb' specifies the on-memory tree database object.
1692 If successful, the return value is the pointer to the
1693 region of the next key, else, it is `NULL'. `NULL' is
1694 returned when no record can be fetched from the iterator.
1695 Because the region of the return value is allocated with
1696 the `malloc' call, it should be released with the `free'
1697 call when it is no longer in use. The order of iteration
1698 is assured to be the same as the stored order.
1699 The function `tcndbfwmkeys' is used in order to get forward matching
1701 keys in an on-memory tree database object.
1702 TCLIST *tcndbfwmkeys(TCNDB *ndb, const void *pbuf, int psiz, int
1704 max);
1705 `ndb' specifies the on-memory tree database object.
1706 `pbuf' specifies the pointer to the region of the prefix.
1707 `psiz' specifies the size of the region of the prefix.
1708 `max' specifies the maximum number of keys to be fetched.
1709 If it is negative, no limit is specified.
1710 The return value is a list object of the corresponding
1711 keys. This function does never fail. It returns an
1712 empty list even if no key corresponds.
1713 Because the object of the return value is created with
1714 the function `tclistnew', it should be deleted with the
1715 function `tclistdel' when it is no longer in use.
1716 The function `tcndbfwmkeys2' is used in order to get forward matching
1718 string keys in an on-memory tree database object.
1719 TCLIST *tcndbfwmkeys2(TCNDB *ndb, const char *pstr, int max);
1721 `ndb' specifies the on-memory tree database object.
1722 `pstr' specifies the string of the prefix.
1723 `max' specifies the maximum number of keys to be fetched.
1724 If it is negative, no limit is specified.
1725 The return value is a list object of the corresponding
1726 keys. This function does never fail. It returns an
1727 empty list even if no key corresponds.
1728 Because the object of the return value is created with
1729 the function `tclistnew', it should be deleted with the
1730 function `tclistdel' when it is no longer in use.
1731 The function `tcndbrnum' is used in order to get the number of records
1733 stored in an on-memory tree database object.
1734 uint64_t tcndbrnum(TCNDB *ndb);
1736 `ndb' specifies the on-memory tree database object.
1737 The return value is the number of the records stored in
1738 the database.
1739 The function `tcndbmsiz' is used in order to get the total size of mem‐
1741 ory used in an on-memory tree database object.
1742 uint64_t tcndbmsiz(TCNDB *ndb);
1744 `ndb' specifies the on-memory tree database object.
1745 The return value is the total size of memory used in the
1746 database.
1747 The function `tcndbaddint' is used in order to add an integer to a
1749 record in an on-memory tree database object.
1750 int tcndbaddint(TCNDB *ndb, const void *kbuf, int ksiz, int
1752 num);
1753 `ndb' specifies the on-memory tree database object.
1754 `kbuf' specifies the pointer to the region of the key.
1755 `ksiz' specifies the size of the region of the key.
1756 `num' specifies the additional value.
1757 The return value is the summation value.
1758 If the corresponding record exists, the value is treated
1759 as an integer and is added to. If no record corresponds,
1760 a new record of the additional value is stored.
1761 The function `tcndbadddouble' is used in order to add a real number to
1763 a record in an on-memory tree database object.
1764 double tcndbadddouble(TCNDB *ndb, const void *kbuf, int ksiz,
1766 double num);
1767 `ndb' specifies the on-memory tree database object.
1768 `kbuf' specifies the pointer to the region of the key.
1769 `ksiz' specifies the size of the region of the key.
1770 `num' specifies the additional value.
1771 The return value is the summation value.
1772 If the corresponding record exists, the value is treated
1773 as a real number and is added to. If no record corre‐
1774 sponds, a new record of the additional value is stored.
1775 The function `tcndbvanish' is used in order to clear an on-memory tree
1777 database object.
1778 void tcndbvanish(TCNDB *ndb);
1780 `ndb' specifies the on-memory tree database object.
1781 All records are removed.
1782 The function `tcndbcutfringe' is used in order to remove fringe records
1784 of an on-memory tree database object.
1785 void tcndbcutfringe(TCNDB *ndb, int num);
1787 `ndb' specifies the on-memory tree database object.
1788 `num' specifies the number of records to be removed.
1789
1792 The function `tcmpoolnew' is used in order to create a memory pool
1793 object.
1794 TCMPOOL *tcmpoolnew(void);
1796 The return value is the new memory pool object.
1797 The function `tcmpooldel' is used in order to delete a memory pool
1799 object.
1800 void tcmpooldel(TCMPOOL *mpool);
1802 `mpool' specifies the memory pool object.
1803 Note that the deleted object and its derivatives can not
1804 be used anymore.
1805 The function `tcmpoolpush' is used in order to relegate an arbitrary
1807 object to a memory pool object.
1808 void *tcmpoolpush(TCMPOOL *mpool, void *ptr, void (*del)(void
1810 *));
1811 `mpool' specifies the memory pool object.
1812 `ptr' specifies the pointer to the object to be rele‐
1813 gated. If it is `NULL', this function has no effect.
1814 `del' specifies the pointer to the function to delete the
1815 object.
1816 The return value is the pointer to the given object.
1817 This function assures that the specified object is
1818 deleted when the memory pool object is deleted.
1819 The function `tcmpoolpushptr' is used in order to relegate an allocated
1821 region to a memory pool object.
1822 void *tcmpoolpushptr(TCMPOOL *mpool, void *ptr);
1824 `mpool' specifies the memory pool object.
1825 `ptr' specifies the pointer to the region to be rele‐
1826 gated. If it is `NULL', this function has no effect.
1827 The return value is the pointer to the given object.
1828 This function assures that the specified region is
1829 released when the memory pool object is deleted.
1830 The function `tcmpoolpushxstr' is used in order to relegate an extensi‐
1832 ble string object to a memory pool object.
1833 TCXSTR *tcmpoolpushxstr(TCMPOOL *mpool, TCXSTR *xstr);
1835 `mpool' specifies the memory pool object.
1836 `xstr' specifies the extensible string object. If it is
1837 `NULL', this function has no effect.
1838 The return value is the pointer to the given object.
1839 This function assures that the specified object is
1840 deleted when the memory pool object is deleted.
1841 The function `tcmpoolpushlist' is used in order to relegate a list
1843 object to a memory pool object.
1844 TCLIST *tcmpoolpushlist(TCMPOOL *mpool, TCLIST *list);
1846 `mpool' specifies the memory pool object.
1847 `list' specifies the list object. If it is `NULL', this
1848 function has no effect.
1849 The return value is the pointer to the given object.
1850 This function assures that the specified object is
1851 deleted when the memory pool object is deleted.
1852 The function `tcmpoolpushmap' is used in order to relegate a map object
1854 to a memory pool object.
1855 TCMAP *tcmpoolpushmap(TCMPOOL *mpool, TCMAP *map);
1857 `mpool' specifies the memory pool object.
1858 `map' specifies the map object. If it is `NULL', this
1859 function has no effect.
1860 The return value is the pointer to the given object.
1861 This function assures that the specified object is
1862 deleted when the memory pool object is deleted.
1863 The function `tcmpoolpushtree' is used in order to relegate a tree
1865 object to a memory pool object.
1866 TCTREE *tcmpoolpushtree(TCMPOOL *mpool, TCTREE *tree);
1868 `mpool' specifies the memory pool object.
1869 `tree' specifies the tree object. If it is `NULL', this
1870 function has no effect.
1871 The return value is the pointer to the given object.
1872 This function assures that the specified object is
1873 deleted when the memory pool object is deleted.
1874 The function `tcmpoolmalloc' is used in order to allocate a region rel‐
1876 egated to a memory pool object.
1877 void *tcmpoolmalloc(TCMPOOL *mpool, size_t size);
1879 `mpool' specifies the memory pool object.
1880 The return value is the pointer to the allocated region
1881 under the memory pool.
1882 The function `tcmpoolxstrnew' is used in order to create an extensible
1884 string object relegated to a memory pool object.
1885 TCXSTR *tcmpoolxstrnew(TCMPOOL *mpool);
1887 The return value is the new extensible string object
1888 under the memory pool.
1889 The function `tcmpoollistnew' is used in order to create a list object
1891 relegated to a memory pool object.
1892 TCLIST *tcmpoollistnew(TCMPOOL *mpool);
1894 The return value is the new list object under the memory
1895 pool.
1896 The function `tcmpoolmapnew' is used in order to create a map object
1898 relegated to a memory pool object.
1899 TCMAP *tcmpoolmapnew(TCMPOOL *mpool);
1901 The return value is the new map object under the memory
1902 pool.
1903 The function `tcmpooltreenew' is used in order to create a tree object
1905 relegated to a memory pool object.
1906 TCTREE *tcmpooltreenew(TCMPOOL *mpool);
1908 The return value is the new tree object under the memory
1909 pool.
1910 The function `tcmpoolpop' is used in order to remove the most recently
1912 installed cleanup handler.
1913 void tcmpoolpop(TCMPOOL *mpool, bool exe);
1915 `mpool' specifies the memory pool object.
1916 `exe' specifies whether to execute the destructor of the
1917 removed handler.
1918 The function `tcmpoolglobal' is used in order to get the global memory
1920 pool object.
1921 TCMPOOL *tcmpoolglobal(void);
1923 The return value is the global memory pool object.
1924 The global memory pool object is a singleton and assured
1925 to be deleted when the process is terminating normally.
1926
1929 The function `tclmax' is used in order to get the larger value of two
1930 integers.
1931 long tclmax(long a, long b);
1933 `a' specifies an integer.
1934 `b' specifies the other integer.
1935 The return value is the larger value of the two.
1936 The function `tclmin' is used in order to get the lesser value of two
1938 integers.
1939 long tclmin(long a, long b);
1941 `a' specifies an integer.
1942 `b' specifies the other integer.
1943 The return value is the lesser value of the two.
1944 The function `tclrand' is used in order to get a random number as long
1946 integer based on uniform distribution.
1947 unsigned long tclrand(void);
1949 The return value is the random number between 0 and
1950 `ULONG_MAX'.
1951 This function uses the random number source device and
1952 generates a real random number if possible.
1953 The function `tcdrand' is used in order to get a random number as dou‐
1955 ble decimal based on uniform distribution.
1956 double tcdrand(void);
1958 The return value is the random number equal to or greater
1959 than 0, and less than 1.0.
1960 This function uses the random number source device and
1961 generates a real random number if possible.
1962 The function `tcdrandnd' is used in order to get a random number as
1964 double decimal based on normal distribution.
1965 double tcdrandnd(double avg, double sd);
1967 `avg' specifies the average.
1968 `sd' specifies the standard deviation.
1969 The return value is the random number.
1970 This function uses the random number source device and
1971 generates a real random number if possible.
1972 The function `tcstricmp' is used in order to compare two strings with
1974 case insensitive evaluation.
1975 int tcstricmp(const char *astr, const char *bstr);
1977 `astr' specifies a string.
1978 `bstr' specifies of the other string.
1979 The return value is positive if the former is big, nega‐
1980 tive if the latter is big, 0 if both are equivalent.
1981 The function `tcstrfwm' is used in order to check whether a string
1983 begins with a key.
1984 bool tcstrfwm(const char *str, const char *key);
1986 `str' specifies the target string.
1987 `key' specifies the forward matching key string.
1988 The return value is true if the target string begins with
1989 the key, else, it is false.
1990 The function `tcstrifwm' is used in order to check whether a string
1992 begins with a key with case insensitive evaluation.
1993 bool tcstrifwm(const char *str, const char *key);
1995 `str' specifies the target string.
1996 `key' specifies the forward matching key string.
1997 The return value is true if the target string begins with
1998 the key, else, it is false.
1999 The function `tcstrbwm' is used in order to check whether a string ends
2001 with a key.
2002 bool tcstrbwm(const char *str, const char *key);
2004 `str' specifies the target string.
2005 `key' specifies the backward matching key string.
2006 The return value is true if the target string ends with
2007 the key, else, it is false.
2008 The function `tcstribwm' is used in order to check whether a string
2010 ends with a key with case insensitive evaluation.
2011 bool tcstribwm(const char *str, const char *key);
2013 `str' specifies the target string.
2014 `key' specifies the backward matching key string.
2015 The return value is true if the target string ends with
2016 the key, else, it is false.
2017 The function `tcstrdist' is used in order to calculate the edit dis‐
2019 tance of two strings.
2020 int tcstrdist(const char *astr, const char *bstr);
2022 `astr' specifies a string.
2023 `bstr' specifies of the other string.
2024 The return value is the edit distance which is known as
2025 the Levenshtein distance. The cost is calculated by
2026 byte.
2027 The function `tcstrdistutf' is used in order to calculate the edit dis‐
2029 tance of two UTF-8 strings.
2030 int tcstrdistutf(const char *astr, const char *bstr);
2032 `astr' specifies a string.
2033 `bstr' specifies of the other string.
2034 The return value is the edit distance which is known as
2035 the Levenshtein distance. The cost is calculated by Uni‐
2036 code character.
2037 The function `tcstrtoupper' is used in order to convert the letters of
2039 a string into upper case.
2040 char *tcstrtoupper(char *str);
2042 `str' specifies the string to be converted.
2043 The return value is the string itself.
2044 The function `tcstrtolower' is used in order to convert the letters of
2046 a string into lower case.
2047 char *tcstrtolower(char *str);
2049 `str' specifies the string to be converted.
2050 The return value is the string itself.
2051 The function `tcstrtrim' is used in order to cut space characters at
2053 head or tail of a string.
2054 char *tcstrtrim(char *str);
2056 `str' specifies the string to be converted.
2057 The return value is the string itself.
2058 The function `tcstrsqzspc' is used in order to squeeze space characters
2060 in a string and trim it.
2061 char *tcstrsqzspc(char *str);
2063 `str' specifies the string to be converted.
2064 The return value is the string itself.
2065 The function `tcstrsubchr' is used in order to substitute characters in
2067 a string.
2068 char *tcstrsubchr(char *str, const char *rstr, const char
2070 *sstr);
2071 `str' specifies the string to be converted.
2072 `rstr' specifies the string containing characters to be
2073 replaced.
2074 `sstr' specifies the string containing characters to be
2075 substituted.
2076 If the substitute string is shorter then the replacement
2077 string, corresponding characters are removed.
2078 The function `tcstrcntutf' is used in order to count the number of
2080 characters in a string of UTF-8.
2081 int tcstrcntutf(const char *str);
2083 `str' specifies the string of UTF-8.
2084 The return value is the number of characters in the
2085 string.
2086 The function `tcstrcututf' is used in order to cut a string of UTF-8 at
2088 the specified number of characters.
2089 char *tcstrcututf(char *str, int num);
2091 `str' specifies the string of UTF-8.
2092 `num' specifies the number of characters to be kept.
2093 The return value is the string itself.
2094 The function `tcstrutftoucs' is used in order to convert a UTF-8 string
2096 into a UCS-2 array.
2097 void tcstrutftoucs(const char *str, uint16_t *ary, int *np);
2099 `str' specifies the UTF-8 string.
2100 `ary' specifies the pointer to the region into which the
2101 result UCS-2 codes are written. The size of the buffer
2102 should be sufficient.
2103 `np' specifies the pointer to a variable into which the
2104 number of elements of the result array is assigned.
2105 The function `tcstrucstoutf' is used in order to convert a UCS-2 array
2107 into a UTF-8 string.
2108 int tcstrucstoutf(const uint16_t *ary, int num, char *str);
2110 `ary' specifies the array of UCS-2 codes.
2111 `num' specifies the number of the array.
2112 `str' specifies the pointer to the region into which the
2113 result UTF-8 string is written. The size of the buffer
2114 should be sufficient.
2115 The return value is the length of the result string.
2116 The function `tcstrsplit' is used in order to create a list object by
2118 splitting a string.
2119 TCLIST *tcstrsplit(const char *str, const char *delims);
2121 `str' specifies the source string.
2122 `delims' specifies a string containing delimiting charac‐
2123 ters.
2124 The return value is a list object of the split elements.
2125 If two delimiters are successive, it is assumed that an
2126 empty element is between the two. Because the object of
2127 the return value is created with the function `tclist‐
2128 new', it should be deleted with the function `tclistdel'
2129 when it is no longer in use.
2130 The function `tcstrjoin' is used in order to create a string by joining
2132 all elements of a list object.
2133 char *tcstrjoin(const TCLIST *list, char delim);
2135 `list' specifies a list object.
2136 `delim' specifies a delimiting character.
2137 The return value is the result string.
2138 Because the region of the return value is allocated with
2139 the `malloc' call, it should be released with the `free'
2140 call when it is no longer in use.
2141 The function `tcatoi' is used in order to convert a string to an inte‐
2143 ger.
2144 int64_t tcatoi(const char *str);
2146 `str' specifies the string.
2147 The return value is the integer. If the string does not
2148 contain numeric expression, 0 is returned.
2149 This function is equivalent to `atoll' except that it
2150 does not depend on the locale.
2151 The function `tcatoix' is used in order to convert a string with a met‐
2153 ric prefix to an integer.
2154 int64_t tcatoix(const char *str);
2156 `str' specifies the string, which can be trailed by a
2157 binary metric prefix. "K", "M", "G", "T", "P", and "E"
2158 are supported. They are case-insensitive.
2159 The return value is the integer. If the string does not
2160 contain numeric expression, 0 is returned. If the inte‐
2161 ger overflows the domain, `INT64_MAX' or `INT64_MIN' is
2162 returned according to the sign.
2163 The function `tcatof' is used in order to convert a string to a real
2165 number.
2166 double tcatof(const char *str);
2168 `str' specifies the string.
2169 The return value is the real number. If the string does
2170 not contain numeric expression, 0.0 is returned.
2171 This function is equivalent to `atof' except that it does
2172 not depend on the locale.
2173 The function `tcregexmatch' is used in order to check whether a string
2175 matches a regular expression.
2176 bool tcregexmatch(const char *str, const char *regex);
2178 `str' specifies the target string.
2179 `regex' specifies the regular expression string. If it
2180 begins with `*', the trailing substring is used as a
2181 case-insensitive regular expression.
2182 The return value is true if matching is success, else, it
2183 is false.
2184 The function `tcregexreplace' is used in order to replace each sub‐
2186 string matching a regular expression string.
2187 char *tcregexreplace(const char *str, const char *regex, const
2189 char *alt);
2190 `str' specifies the target string.
2191 `regex' specifies the regular expression string for sub‐
2192 strings. If it begins with `*', the trailing substring
2193 is used as a case-insensitive regular expression.
2194 `alt' specifies the alternative string with which each
2195 substrings is replaced. Each `&' in the string is
2196 replaced with the matched substring. Each `´ in the
2197 string escapes the following character. Special escapes
2198 "1" through "9" referring to the corresponding matching
2199 sub-expressions in the regular expression string are sup‐
2200 ported.
2201 The return value is a new converted string. Even if the
2202 regular expression is invalid, a copy of the original
2203 string is returned.
2204 Because the region of the return value is allocated with
2205 the `malloc' call, it should be released with the `free'
2206 call when it is no longer in use.
2207 The function `tcmd5hash' is used in order to get the MD5 hash value of
2209 a serial object.
2210 void tcmd5hash(const void *ptr, int size, char *buf);
2212 `ptr' specifies the pointer to the region.
2213 `size' specifies the size of the region.
2214 `buf' specifies the pointer to the region into which the
2215 result string is written. The size of the buffer should
2216 be equal to or more than 48 bytes.
2217 The function `tcarccipher' is used in order to cipher or decipher a
2219 serial object with the Arcfour stream cipher.
2220 void tcarccipher(const void *ptr, int size, const void *kbuf,
2222 int ksiz, void *obuf);
2223 `ptr' specifies the pointer to the region.
2224 `size' specifies the size of the region.
2225 `kbuf' specifies the pointer to the region of the cipher
2226 key.
2227 `ksiz' specifies the size of the region of the cipher
2228 key.
2229 `obuf' specifies the pointer to the region into which the
2230 result data is written. The size of the buffer should be
2231 equal to or more than the input region.
2232 The function `tctime' is used in order to get the time of day in sec‐
2234 onds.
2235 double tctime(void);
2237 The return value is the time of day in seconds. The
2238 accuracy is in microseconds.
2239 The function `tccalendar' is used in order to get the Gregorian calen‐
2241 dar of a time.
2242 void tccalendar(int64_t t, int jl, int *yearp, int *monp, int
2244 *dayp, int *hourp, int *minp, int *secp);
2245 `t' specifies the source time in seconds from the epoch.
2246 If it is `INT64_MAX', the current time is specified.
2247 `jl' specifies the jet lag of a location in seconds. If
2248 it is `INT_MAX', the local jet lag is specified.
2249 `yearp' specifies the pointer to a variable to which the
2250 year is assigned. If it is `NULL', it is not used.
2251 `monp' specifies the pointer to a variable to which the
2252 month is assigned. If it is `NULL', it is not used. 1
2253 means January and 12 means December.
2254 `dayp' specifies the pointer to a variable to which the
2255 day of the month is assigned. If it is `NULL', it is not
2256 used.
2257 `hourp' specifies the pointer to a variable to which the
2258 hours is assigned. If it is `NULL', it is not used.
2259 `minp' specifies the pointer to a variable to which the
2260 minutes is assigned. If it is `NULL', it is not used.
2261 `secp' specifies the pointer to a variable to which the
2262 seconds is assigned. If it is `NULL', it is not used.
2263 The function `tcdatestrwww' is used in order to format a date as a
2265 string in W3CDTF.
2266 void tcdatestrwww(int64_t t, int jl, char *buf);
2268 `t' specifies the source time in seconds from the epoch.
2269 If it is `INT64_MAX', the current time is specified.
2270 `jl' specifies the jet lag of a location in seconds. If
2271 it is `INT_MAX', the local jet lag is specified.
2272 `buf' specifies the pointer to the region into which the
2273 result string is written. The size of the buffer should
2274 be equal to or more than 48 bytes.
2275 W3CDTF represents a date as "YYYY-MM-DDThh:mm:ddTZD".
2276 The function `tcdatestrhttp' is used in order to format a date as a
2278 string in RFC 1123 format.
2279 void tcdatestrhttp(int64_t t, int jl, char *buf);
2281 `t' specifies the source time in seconds from the epoch.
2282 If it is `INT64_MAX', the current time is specified.
2283 `jl' specifies the jet lag of a location in seconds. If
2284 it is `INT_MAX', the local jet lag is specified.
2285 `buf' specifies the pointer to the region into which the
2286 result string is written. The size of the buffer should
2287 be equal to or more than 48 bytes.
2288 RFC 1123 format represents a date as "Wdy, DD-Mon-YYYY
2289 hh:mm:dd TZD".
2290 The function `tcstrmktime' is used in order to get the time value of a
2292 date string.
2293 int64_t tcstrmktime(const char *str);
2295 `str' specifies the date string in decimal, hexadecimal,
2296 W3CDTF, or RFC 822 (1123). Decimal can be trailed by "s"
2297 for in seconds, "m" for in minutes, "h" for in hours, and
2298 "d" for in days.
2299 The return value is the time value of the date or
2300 `INT64_MIN' if the format is invalid.
2301 The function `tcjetlag' is used in order to get the jet lag of the
2303 local time.
2304 int tcjetlag(void);
2306 The return value is the jet lag of the local time in sec‐
2307 onds.
2308 The function `tcdayofweek' is used in order to get the day of week of a
2310 date.
2311 int tcdayofweek(int year, int mon, int day);
2313 `year' specifies the year of a date.
2314 `mon' specifies the month of the date.
2315 `day' specifies the day of the date.
2316 The return value is the day of week of the date. 0 means
2317 Sunday and 6 means Saturday.
2318
2321 The function `tcrealpath' is used in order to get the canonicalized
2322 absolute path of a file.
2323 char *tcrealpath(const char *path);
2325 `path' specifies the path of the file.
2326 The return value is the canonicalized absolute path of a
2327 file, or `NULL' if the path is invalid.
2328 Because the region of the return value is allocated with
2329 the `malloc' call, it should be released with the `free'
2330 call when it is no longer in use.
2331 The function `tcstatfile' is used in order to get the status informa‐
2333 tion of a file.
2334 bool tcstatfile(const char *path, bool *isdirp, int64_t *sizep,
2336 int64_t *mtimep);
2337 `path' specifies the path of the file.
2338 `isdirp' specifies the pointer to a variable into which
2339 whether the file is a directory is assigned. If it is
2340 `NULL', it is ignored.
2341 `sizep' specifies the pointer to a variable into which
2342 the size of the file is assigned. If it is `NULL', it is
2343 ignored.
2344 `ntimep' specifies the pointer to a variable into which
2345 the size of the file is assigned. If it is `NULL', it is
2346 ignored.
2347 If successful, the return value is true, else, it is
2348 false.
2349 The function `tcreadfile' is used in order to read whole data of a
2351 file.
2352 void *tcreadfile(const char *path, int limit, int *sp);
2354 `path' specifies the path of the file. If it is `NULL',
2355 the standard input is specified.
2356 `limit' specifies the limiting size of reading data. If
2357 it is not more than 0, the limitation is not specified.
2358 `sp' specifies the pointer to the variable into which the
2359 size of the region of the return value is assigned. If
2360 it is `NULL', it is not used.
2361 The return value is the pointer to the allocated region
2362 of the read data, or `NULL' if the file could not be
2363 opened.
2364 Because an additional zero code is appended at the end of
2365 the region of the return value, the return value can be
2366 treated as a character string. Because the region of the
2367 return value is allocated with the `malloc' call, it
2368 should be released with the `free' call when when is no
2369 longer in use.
2370 The function `tcreadfilelines' is used in order to read every line of a
2372 file.
2373 TCLIST *tcreadfilelines(const char *path);
2375 `path' specifies the path of the file. If it is `NULL',
2376 the standard input is specified.
2377 The return value is a list object of every lines if suc‐
2378 cessful, else it is `NULL'.
2379 Line separators are cut out. Because the object of the
2380 return value is created with the function `tclistnew', it
2381 should be deleted with the function `tclistdel' when it
2382 is no longer in use.
2383 The function `tcwritefile' is used in order to write data into a file.
2385 bool tcwritefile(const char *path, const void *ptr, int size);
2387 `path' specifies the path of the file. If it is `NULL',
2388 the standard output is specified.
2389 `ptr' specifies the pointer to the data region.
2390 `size' specifies the size of the region.
2391 If successful, the return value is true, else, it is
2392 false.
2393 The function `tccopyfile' is used in order to copy a file.
2395 bool tccopyfile(const char *src, const char *dest);
2397 `src' specifies the path of the source file.
2398 `dest' specifies the path of the destination file.
2399 The return value is true if successful, else, it is
2400 false.
2401 If the destination file exists, it is overwritten.
2402 The function `tcreaddir' is used in order to read names of files in a
2404 directory.
2405 TCLIST *tcreaddir(const char *path);
2407 `path' specifies the path of the directory.
2408 The return value is a list object of names if successful,
2409 else it is `NULL'.
2410 Links to the directory itself and to the parent directory
2411 are ignored.
2412 Because the object of the return value is created with
2413 the function `tclistnew', it should be deleted with the
2414 function `tclistdel' when it is no longer in use.
2415 The function `tcglobpat' is used in order to expand a pattern into a
2417 list of matched paths.
2418 TCLIST *tcglobpat(const char *pattern);
2420 `pattern' specifies the matching pattern.
2421 The return value is a list object of matched paths. If
2422 no path is matched, an empty list is returned.
2423 Because the object of the return value is created with
2424 the function `tclistnew', it should be deleted with the
2425 function `tclistdel' when it is no longer in use.
2426 The function `tcremovelink' is used in order to remove a file or a
2428 directory and its sub ones recursively.
2429 bool tcremovelink(const char *path);
2431 `path' specifies the path of the link.
2432 If successful, the return value is true, else, it is
2433 false. False is returned when the link does not exist or
2434 the permission is denied.
2435 The function `tcwrite' is used in order to write data into a file.
2437 bool tcwrite(int fd, const void *buf, size_t size);
2439 `fd' specifies the file descriptor.
2440 `buf' specifies the buffer to be written.
2441 `size' specifies the size of the buffer.
2442 The return value is true if successful, else, it is
2443 false.
2444 The function `tcread' is used in order to read data from a file.
2446 bool tcread(int fd, void *buf, size_t size);
2448 `fd' specifies the file descriptor.
2449 `buf' specifies the buffer to store into.
2450 `size' specifies the size of the buffer.
2451 The return value is true if successful, else, it is
2452 false.
2453 The function `tclock' is used in order to lock a file.
2455 bool tclock(int fd, bool ex, bool nb);
2457 `fd' specifies the file descriptor.
2458 `ex' specifies whether an exclusive lock or a shared lock
2459 is performed.
2460 `nb' specifies whether to request with non-blocking.
2461 The return value is true if successful, else, it is
2462 false.
2463 The function `tcunlock' is used in order to unlock a file.
2465 bool tcunlock(int fd);
2467 `fd' specifies the file descriptor.
2468 The return value is true if successful, else, it is
2469 false.
2470 The function `tcsystem' is used in order to execute a shell command.
2472 int tcsystem(const char **args, int anum);
2474 `args' specifies an array of the command name and its
2475 arguments.
2476 `anum' specifies the number of elements of the array.
2477 The return value is the exit code of the command or
2478 `INT_MAX' on failure.
2479 The command name and the arguments are quoted and meta
2480 characters are escaped.
2481
2484 The function `tcurlencode' is used in order to encode a serial object
2485 with URL encoding.
2486 char *tcurlencode(const char *ptr, int size);
2488 `ptr' specifies the pointer to the region.
2489 `size' specifies the size of the region.
2490 The return value is the result string.
2491 Because the region of the return value is allocated with
2492 the `malloc' call, it should be released with the `free'
2493 call if when is no longer in use.
2494 The function `tcurldecode' is used in order to decode a string encoded
2496 with URL encoding.
2497 char *tcurldecode(const char *str, int *sp);
2499 `str' specifies the encoded string.
2500 `sp' specifies the pointer to a variable into which the
2501 size of the region of the return value is assigned.
2502 The return value is the pointer to the region of the
2503 result.
2504 Because an additional zero code is appended at the end of
2505 the region of the return value, the return value can be
2506 treated as a character string. Because the region of the
2507 return value is allocated with the `malloc' call, it
2508 should be released with the `free' call when it is no
2509 longer in use.
2510 The function `tcurlbreak' is used in order to break up a URL into ele‐
2512 ments.
2513 TCMAP *tcurlbreak(const char *str);
2515 `str' specifies the URL string.
2516 The return value is the map object whose keys are the
2517 name of elements. The key "self" specifies the URL
2518 itself. The key "scheme" specifies the scheme. The key
2519 "host" specifies the host of the server. The key "port"
2520 specifies the port number of the server. The key
2521 "authority" specifies the authority information. The key
2522 "path" specifies the path of the resource. The key
2523 "file" specifies the file name without the directory sec‐
2524 tion. The key "query" specifies the query string. The
2525 key "fragment" specifies the fragment string.
2526 Supported schema are HTTP, HTTPS, FTP, and FILE. Abso‐
2527 lute URL and relative URL are supported. Because the
2528 object of the return value is created with the function
2529 `tcmapnew', it should be deleted with the function
2530 `tcmapdel' when it is no longer in use.
2531 The function `tcurlresolve' is used in order to resolve a relative URL
2533 with an absolute URL.
2534 char *tcurlresolve(const char *base, const char *target);
2536 `base' specifies the absolute URL of the base location.
2537 `target' specifies the URL to be resolved.
2538 The return value is the resolved URL. If the target URL
2539 is relative, a new URL of relative location from the base
2540 location is returned. Else, a copy of the target URL is
2541 returned.
2542 Because the region of the return value is allocated with
2543 the `malloc' call, it should be released with the `free'
2544 call when it is no longer in use.
2545 The function `tcbaseencode' is used in order to encode a serial object
2547 with Base64 encoding.
2548 char *tcbaseencode(const char *ptr, int size);
2550 `ptr' specifies the pointer to the region.
2551 `size' specifies the size of the region.
2552 The return value is the result string.
2553 Because the region of the return value is allocated with
2554 the `malloc' call, it should be released with the `free'
2555 call if when is no longer in use.
2556 The function `tcbasedecode' is used in order to decode a string encoded
2558 with Base64 encoding.
2559 char *tcbasedecode(const char *str, int *sp);
2561 `str' specifies the encoded string.
2562 `sp' specifies the pointer to a variable into which the
2563 size of the region of the return value is assigned.
2564 The return value is the pointer to the region of the
2565 result.
2566 Because an additional zero code is appended at the end of
2567 the region of the return value, the return value can be
2568 treated as a character string. Because the region of the
2569 return value is allocated with the `malloc' call, it
2570 should be released with the `free' call when it is no
2571 longer in use.
2572 The function `tcquoteencode' is used in order to encode a serial object
2574 with Quoted-printable encoding.
2575 char *tcquoteencode(const char *ptr, int size);
2577 `ptr' specifies the pointer to the region.
2578 `size' specifies the size of the region.
2579 The return value is the result string.
2580 Because the region of the return value is allocated with
2581 the `malloc' call, it should be released with the `free'
2582 call if when is no longer in use.
2583 The function `tcquotedecode' is used in order to decode a string
2585 encoded with Quoted-printable encoding.
2586 char *tcquotedecode(const char *str, int *sp);
2588 `str' specifies the encoded string.
2589 `sp' specifies the pointer to a variable into which the
2590 size of the region of the return value is assigned.
2591 The return value is the pointer to the region of the
2592 result.
2593 Because an additional zero code is appended at the end of
2594 the region of the return value, the return value can be
2595 treated as a character string. Because the region of the
2596 return value is allocated with the `malloc' call, it
2597 should be released with the `free' call when it is no
2598 longer in use.
2599 The function `tcmimeencode' is used in order to encode a string with
2601 MIME encoding.
2602 char *tcmimeencode(const char *str, const char *encname, bool
2604 base);
2605 `str' specifies the string.
2606 `encname' specifies the string of the name of the charac‐
2607 ter encoding.
2608 `base' specifies whether to use Base64 encoding. If it
2609 is false, Quoted-printable is used.
2610 The return value is the result string.
2611 Because the region of the return value is allocated with
2612 the `malloc' call, it should be released with the `free'
2613 call when it is no longer in use.
2614 The function `tcmimedecode' is used in order to decode a string encoded
2616 with MIME encoding.
2617 char *tcmimedecode(const char *str, char *enp);
2619 `str' specifies the encoded string.
2620 `enp' specifies the pointer to the region into which the
2621 name of encoding is written. If it is `NULL', it is not
2622 used. The size of the buffer should be equal to or more
2623 than 32 bytes.
2624 The return value is the result string.
2625 Because the region of the return value is allocated with
2626 the `malloc' call, it should be released with the `free'
2627 call when it is no longer in use.
2628 The function `tcmimebreak' is used in order to split a string of MIME
2630 into headers and the body.
2631 char *tcmimebreak(const char *ptr, int size, TCMAP *headers, int
2633 *sp);
2634 `ptr' specifies the pointer to the region of MIME data.
2635 `size' specifies the size of the region.
2636 `headers' specifies a map object to store headers. If it
2637 is `NULL', it is not used. Each key of the map is an
2638 uncapitalized header name.
2639 `sp' specifies the pointer to the variable into which the
2640 size of the region of the return value is assigned.
2641 The return value is the pointer to the region of the body
2642 data.
2643 If the content type is defined, the header map has the
2644 key "TYPE" specifying the type. If the character encod‐
2645 ing is defined, the key "CHARSET" specifies the encoding
2646 name. If the boundary string of multipart is defined,
2647 the key "BOUNDARY" specifies the string. If the content
2648 disposition is defined, the key "DISPOSITION" specifies
2649 the direction. If the file name is defined, the key
2650 "FILENAME" specifies the name. If the attribute name is
2651 defined, the key "NAME" specifies the name. Because the
2652 region of the return value is allocated with the `malloc'
2653 call, it should be released with the `free' call when it
2654 is no longer in use.
2655 The function `tcmimeparts' is used in order to split multipart data of
2657 MIME into its parts.
2658 TCLIST *tcmimeparts(const char *ptr, int size, const char
2660 *boundary);
2661 `ptr' specifies the pointer to the region of multipart
2662 data of MIME.
2663 `size' specifies the size of the region.
2664 `boundary' specifies the boundary string.
2665 The return value is a list object. Each element of the
2666 list is the data of a part.
2667 Because the object of the return value is created with
2668 the function `tclistnew', it should be deleted with the
2669 function `tclistdel' when it is no longer in use.
2670 The function `tchexencode' is used in order to encode a serial object
2672 with hexadecimal encoding.
2673 char *tchexencode(const char *ptr, int size);
2675 `ptr' specifies the pointer to the region.
2676 `size' specifies the size of the region.
2677 The return value is the result string.
2678 Because the region of the return value is allocated with
2679 the `malloc' call, it should be released with the `free'
2680 call if when is no longer in use.
2681 The function `tchexdecode' is used in order to decode a string encoded
2683 with hexadecimal encoding.
2684 char *tchexdecode(const char *str, int *sp);
2686 `str' specifies the encoded string.
2687 `sp' specifies the pointer to a variable into which the
2688 size of the region of the return
2689 value is assigned.
2690 The return value is the pointer to the region of the
2691 result.
2692 Because an additional zero code is appended at the end of
2693 the region of the return value, the return value can be
2694 treated as a character string. Because the region of the
2695 return value is allocated with the `malloc' call, it
2696 should be released with the `free' call when it is no
2697 longer in use.
2698 The function `tcpackencode' is used in order to compress a serial
2700 object with Packbits encoding.
2701 char *tcpackencode(const char *ptr, int size, int *sp);
2703 `ptr' specifies the pointer to the region.
2704 `size' specifies the size of the region.
2705 `sp' specifies the pointer to the variable into which the
2706 size of the region of the return value is assigned.
2707 If successful, the return value is the pointer to the
2708 result object, else, it is `NULL'.
2709 Because the region of the return value is allocated with
2710 the `malloc' call, it should be released with the `free'
2711 call when it is no longer in use.
2712 The function `tcpackdecode' is used in order to decompress a serial
2714 object compressed with Packbits encoding.
2715 char *tcpackdecode(const char *ptr, int size, int *sp);
2717 `ptr' specifies the pointer to the region.
2718 `size' specifies the size of the region.
2719 `sp' specifies the pointer to a variable into which the
2720 size of the region of the return value is assigned.
2721 If successful, the return value is the pointer to the
2722 result object, else, it is `NULL'.
2723 Because an additional zero code is appended at the end of
2724 the region of the return value, the return value can be
2725 treated as a character string. Because the region of the
2726 return value is allocated with the `malloc' call, it
2727 should be released with the `free' call when it is no
2728 longer in use.
2729 The function `tcbsencode' is used in order to compress a serial object
2731 with TCBS encoding.
2732 char *tcbsencode(const char *ptr, int size, int *sp);
2734 `ptr' specifies the pointer to the region.
2735 `size' specifies the size of the region.
2736 `sp' specifies the pointer to the variable into which the
2737 size of the region of the return value is assigned.
2738 If successful, the return value is the pointer to the
2739 result object, else, it is `NULL'.
2740 Because the region of the return value is allocated with
2741 the `malloc' call, it should be released with the `free'
2742 call when it is no longer in use.
2743 The function `tcbsdecode' is used in order to decompress a serial
2745 object compressed with TCBS encoding.
2746 char *tcbsdecode(const char *ptr, int size, int *sp);
2748 `ptr' specifies the pointer to the region.
2749 `size' specifies the size of the region.
2750 `sp' specifies the pointer to a variable into which the
2751 size of the region of the return value is assigned.
2752 If successful, the return value is the pointer to the
2753 result object, else, it is `NULL'.
2754 Because an additional zero code is appended at the end of
2755 the region of the return value, the return value can be
2756 treated as a character string. Because the region of the
2757 return value is allocated with the `malloc' call, it
2758 should be released with the `free' call when it is no
2759 longer in use.
2760 The function `tcdeflate' is used in order to compress a serial object
2762 with Deflate encoding.
2763 char *tcdeflate(const char *ptr, int size, int *sp);
2765 `ptr' specifies the pointer to the region.
2766 `size' specifies the size of the region.
2767 `sp' specifies the pointer to the variable into which the
2768 size of the region of the return value is assigned.
2769 If successful, the return value is the pointer to the
2770 result object, else, it is `NULL'.
2771 Because the region of the return value is allocated with
2772 the `malloc' call, it should be released with the `free'
2773 call when it is no longer in use.
2774 The function `tcinflate' is used in order to decompress a serial object
2776 compressed with Deflate encoding.
2777 char *tcinflate(const char *ptr, int size, int *sp);
2779 `ptr' specifies the pointer to the region.
2780 `size' specifies the size of the region.
2781 `sp' specifies the pointer to a variable into which the
2782 size of the region of the return value is assigned.
2783 If successful, the return value is the pointer to the
2784 result object, else, it is `NULL'.
2785 Because an additional zero code is appended at the end of
2786 the region of the return value, the return value can be
2787 treated as a character string. Because the region of the
2788 return value is allocated with the `malloc' call, it
2789 should be released with the `free' call when it is no
2790 longer in use.
2791 The function `tcgzipencode' is used in order to compress a serial
2793 object with GZIP encoding.
2794 char *tcgzipencode(const char *ptr, int size, int *sp);
2796 `ptr' specifies the pointer to the region.
2797 `size' specifies the size of the region.
2798 `sp' specifies the pointer to the variable into which the
2799 size of the region of the return value is assigned.
2800 If successful, the return value is the pointer to the
2801 result object, else, it is `NULL'.
2802 Because the region of the return value is allocated with
2803 the `malloc' call, it should be released with the `free'
2804 call when it is no longer in use.
2805 The function `tcgzipdecode' is used in order to decompress a serial
2807 object compressed with GZIP encoding.
2808 char *tcgzipdecode(const char *ptr, int size, int *sp);
2810 `ptr' specifies the pointer to the region.
2811 `size' specifies the size of the region.
2812 `sp' specifies the pointer to a variable into which the
2813 size of the region of the return value is assigned.
2814 If successful, the return value is the pointer to the
2815 result object, else, it is `NULL'.
2816 Because an additional zero code is appended at the end of
2817 the region of the return value, the return value can be
2818 treated as a character string. Because the region of the
2819 return value is allocated with the `malloc' call, it
2820 should be released with the `free' call when it is no
2821 longer in use.
2822 The function `tcgetcrc' is used in order to get the CRC32 checksum of a
2824 serial object.
2825 unsigned int tcgetcrc(const char *ptr, int size);
2827 `ptr' specifies the pointer to the region.
2828 `size' specifies the size of the region.
2829 The return value is the CRC32 checksum of the object.
2830 The function `tcbzipencode' is used in order to compress a serial
2832 object with BZIP2 encoding.
2833 char *tcbzipencode(const char *ptr, int size, int *sp);
2835 `ptr' specifies the pointer to the region.
2836 `size' specifies the size of the region.
2837 `sp' specifies the pointer to the variable into which the
2838 size of the region of the return value is assigned.
2839 If successful, the return value is the pointer to the
2840 result object, else, it is `NULL'.
2841 Because the region of the return value is allocated with
2842 the `malloc' call, it should be released with the `free'
2843 call when it is no longer in use.
2844 The function `tcbzipdecode' is used in order to decompress a serial
2846 object compressed with BZIP2 encoding.
2847 char *tcbzipdecode(const char *ptr, int size, int *sp);
2849 `ptr' specifies the pointer to the region.
2850 `size' specifies the size of the region.
2851 `sp' specifies the pointer to a variable into which the
2852 size of the region of the return value is assigned.
2853 If successful, the return value is the pointer to the
2854 result object, else, it is `NULL'.
2855 Because an additional zero code is appended at the end of
2856 the region of the return value, the return value can be
2857 treated as a character string. Because the region of the
2858 return value is allocated with the `malloc' call, it
2859 should be released with the `free' call when it is no
2860 longer in use.
2861 The function `tcberencode' is used in order to encode an array of non‐
2863 negative integers with BER encoding.
2864 char *tcberencode(const unsigned int *ary, int anum, int *sp);
2866 `ary' specifies the pointer to the array of nonnegative
2867 integers.
2868 `anum' specifies the size of the array.
2869 `sp' specifies the pointer to a variable into which the
2870 size of the region of the return value is assigned.
2871 The return value is the pointer to the region of the
2872 result.
2873 Because the region of the return value is allocated with
2874 the `malloc' call, it should be released with the `free'
2875 call if when is no longer in use.
2876 The function `tcberdecode' is used in order to decode a serial object
2878 encoded with BER encoding.
2879 unsigned int *tcberdecode(const char *ptr, int size, int *np);
2881 `ptr' specifies the pointer to the region.
2882 `size' specifies the size of the region.
2883 `np' specifies the pointer to a variable into which the
2884 number of elements of the return value is assigned.
2885 The return value is the pointer to the array of the
2886 result.
2887 Because the region of the return value is allocated with
2888 the `malloc' call, it should be released with the `free'
2889 call if when is no longer in use.
2890 The function `tcxmlescape' is used in order to escape meta characters
2892 in a string with the entity references of XML.
2893 char *tcxmlescape(const char *str);
2895 `str' specifies the string.
2896 The return value is the pointer to the escaped string.
2897 This function escapes only `&', `<', `>', and `"'.
2898 Because the region of the return value is allocated with
2899 the `malloc' call, it should be released with the `free'
2900 call when it is no longer in use.
2901 The function `tcxmlunescape' is used in order to unescape entity refer‐
2903 ences in a string of XML.
2904 char *tcxmlunescape(const char *str);
2906 `str' specifies the string.
2907 The return value is the unescaped string.
2908 This function restores only `&', `<', `>', and
2909 `"'. Because the region of the return value is
2910 allocated with the `malloc' call, it should be released
2911 with the `free' call when it is no longer in use.
2912
2915 tcutest(1), tcucodec(1), tokyocabinet(3)
2916Man Page 2009-09-04 TCUTIL(3)