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 of a memory pool object.
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 `tcmpoolclear' is used in order to remove all cleanup han‐
1920 dler of a memory pool object.
1921 void tcmpoolclear(TCMPOOL *mpool, bool exe);
1923 `mpool' specifies the memory pool object.
1924 `exe' specifies whether to execute the destructors of the
1925 removed handlers.
1926 The function `tcmpoolglobal' is used in order to get the global memory
1928 pool object.
1929 TCMPOOL *tcmpoolglobal(void);
1931 The return value is the global memory pool object.
1932 The global memory pool object is a singleton and assured
1933 to be deleted when the process is terminating normally.
1934
1937 The function `tclmax' is used in order to get the larger value of two
1938 integers.
1939 long tclmax(long a, long b);
1941 `a' specifies an integer.
1942 `b' specifies the other integer.
1943 The return value is the larger value of the two.
1944 The function `tclmin' is used in order to get the lesser value of two
1946 integers.
1947 long tclmin(long a, long b);
1949 `a' specifies an integer.
1950 `b' specifies the other integer.
1951 The return value is the lesser value of the two.
1952 The function `tclrand' is used in order to get a random number as long
1954 integer based on uniform distribution.
1955 unsigned long tclrand(void);
1957 The return value is the random number between 0 and
1958 `ULONG_MAX'.
1959 This function uses the random number source device and
1960 generates a real random number if possible.
1961 The function `tcdrand' is used in order to get a random number as dou‐
1963 ble decimal based on uniform distribution.
1964 double tcdrand(void);
1966 The return value is the random number equal to or greater
1967 than 0, and less than 1.0.
1968 This function uses the random number source device and
1969 generates a real random number if possible.
1970 The function `tcdrandnd' is used in order to get a random number as
1972 double decimal based on normal distribution.
1973 double tcdrandnd(double avg, double sd);
1975 `avg' specifies the average.
1976 `sd' specifies the standard deviation.
1977 The return value is the random number.
1978 This function uses the random number source device and
1979 generates a real random number if possible.
1980 The function `tcstricmp' is used in order to compare two strings with
1982 case insensitive evaluation.
1983 int tcstricmp(const char *astr, const char *bstr);
1985 `astr' specifies a string.
1986 `bstr' specifies of the other string.
1987 The return value is positive if the former is big, nega‐
1988 tive if the latter is big, 0 if both are equivalent.
1989 The function `tcstrfwm' is used in order to check whether a string
1991 begins with a key.
1992 bool tcstrfwm(const char *str, const char *key);
1994 `str' specifies the target string.
1995 `key' specifies the forward matching key string.
1996 The return value is true if the target string begins with
1997 the key, else, it is false.
1998 The function `tcstrifwm' is used in order to check whether a string
2000 begins with a key with case insensitive evaluation.
2001 bool tcstrifwm(const char *str, const char *key);
2003 `str' specifies the target string.
2004 `key' specifies the forward matching key string.
2005 The return value is true if the target string begins with
2006 the key, else, it is false.
2007 The function `tcstrbwm' is used in order to check whether a string ends
2009 with a key.
2010 bool tcstrbwm(const char *str, const char *key);
2012 `str' specifies the target string.
2013 `key' specifies the backward matching key string.
2014 The return value is true if the target string ends with
2015 the key, else, it is false.
2016 The function `tcstribwm' is used in order to check whether a string
2018 ends with a key with case insensitive evaluation.
2019 bool tcstribwm(const char *str, const char *key);
2021 `str' specifies the target string.
2022 `key' specifies the backward matching key string.
2023 The return value is true if the target string ends with
2024 the key, else, it is false.
2025 The function `tcstrdist' is used in order to calculate the edit dis‐
2027 tance of two strings.
2028 int tcstrdist(const char *astr, const char *bstr);
2030 `astr' specifies a string.
2031 `bstr' specifies of the other string.
2032 The return value is the edit distance which is known as
2033 the Levenshtein distance. The cost is calculated by
2034 byte.
2035 The function `tcstrdistutf' is used in order to calculate the edit dis‐
2037 tance of two UTF-8 strings.
2038 int tcstrdistutf(const char *astr, const char *bstr);
2040 `astr' specifies a string.
2041 `bstr' specifies of the other string.
2042 The return value is the edit distance which is known as
2043 the Levenshtein distance. The cost is calculated by Uni‐
2044 code character.
2045 The function `tcstrtoupper' is used in order to convert the letters of
2047 a string into upper case.
2048 char *tcstrtoupper(char *str);
2050 `str' specifies the string to be converted.
2051 The return value is the string itself.
2052 The function `tcstrtolower' is used in order to convert the letters of
2054 a string into lower case.
2055 char *tcstrtolower(char *str);
2057 `str' specifies the string to be converted.
2058 The return value is the string itself.
2059 The function `tcstrtrim' is used in order to cut space characters at
2061 head or tail of a string.
2062 char *tcstrtrim(char *str);
2064 `str' specifies the string to be converted.
2065 The return value is the string itself.
2066 The function `tcstrsqzspc' is used in order to squeeze space characters
2068 in a string and trim it.
2069 char *tcstrsqzspc(char *str);
2071 `str' specifies the string to be converted.
2072 The return value is the string itself.
2073 The function `tcstrsubchr' is used in order to substitute characters in
2075 a string.
2076 char *tcstrsubchr(char *str, const char *rstr, const char
2078 *sstr);
2079 `str' specifies the string to be converted.
2080 `rstr' specifies the string containing characters to be
2081 replaced.
2082 `sstr' specifies the string containing characters to be
2083 substituted.
2084 If the substitute string is shorter then the replacement
2085 string, corresponding characters are removed.
2086 The function `tcstrcntutf' is used in order to count the number of
2088 characters in a string of UTF-8.
2089 int tcstrcntutf(const char *str);
2091 `str' specifies the string of UTF-8.
2092 The return value is the number of characters in the
2093 string.
2094 The function `tcstrcututf' is used in order to cut a string of UTF-8 at
2096 the specified number of characters.
2097 char *tcstrcututf(char *str, int num);
2099 `str' specifies the string of UTF-8.
2100 `num' specifies the number of characters to be kept.
2101 The return value is the string itself.
2102 The function `tcstrutftoucs' is used in order to convert a UTF-8 string
2104 into a UCS-2 array.
2105 void tcstrutftoucs(const char *str, uint16_t *ary, int *np);
2107 `str' specifies the UTF-8 string.
2108 `ary' specifies the pointer to the region into which the
2109 result UCS-2 codes are written. The size of the buffer
2110 should be sufficient.
2111 `np' specifies the pointer to a variable into which the
2112 number of elements of the result array is assigned.
2113 The function `tcstrucstoutf' is used in order to convert a UCS-2 array
2115 into a UTF-8 string.
2116 int tcstrucstoutf(const uint16_t *ary, int num, char *str);
2118 `ary' specifies the array of UCS-2 codes.
2119 `num' specifies the number of the array.
2120 `str' specifies the pointer to the region into which the
2121 result UTF-8 string is written. The size of the buffer
2122 should be sufficient.
2123 The return value is the length of the result string.
2124 The function `tcstrsplit' is used in order to create a list object by
2126 splitting a string.
2127 TCLIST *tcstrsplit(const char *str, const char *delims);
2129 `str' specifies the source string.
2130 `delims' specifies a string containing delimiting charac‐
2131 ters.
2132 The return value is a list object of the split elements.
2133 If two delimiters are successive, it is assumed that an
2134 empty element is between the two. Because the object of
2135 the return value is created with the function `tclist‐
2136 new', it should be deleted with the function `tclistdel'
2137 when it is no longer in use.
2138 The function `tcstrjoin' is used in order to create a string by joining
2140 all elements of a list object.
2141 char *tcstrjoin(const TCLIST *list, char delim);
2143 `list' specifies a list object.
2144 `delim' specifies a delimiting character.
2145 The return value is the result string.
2146 Because the region of the return value is allocated with
2147 the `malloc' call, it should be released with the `free'
2148 call when it is no longer in use.
2149 The function `tcatoi' is used in order to convert a string to an inte‐
2151 ger.
2152 int64_t tcatoi(const char *str);
2154 `str' specifies the string.
2155 The return value is the integer. If the string does not
2156 contain numeric expression, 0 is returned.
2157 This function is equivalent to `atoll' except that it
2158 does not depend on the locale.
2159 The function `tcatoix' is used in order to convert a string with a met‐
2161 ric prefix to an integer.
2162 int64_t tcatoix(const char *str);
2164 `str' specifies the string, which can be trailed by a
2165 binary metric prefix. "K", "M", "G", "T", "P", and "E"
2166 are supported. They are case-insensitive.
2167 The return value is the integer. If the string does not
2168 contain numeric expression, 0 is returned. If the inte‐
2169 ger overflows the domain, `INT64_MAX' or `INT64_MIN' is
2170 returned according to the sign.
2171 The function `tcatof' is used in order to convert a string to a real
2173 number.
2174 double tcatof(const char *str);
2176 `str' specifies the string.
2177 The return value is the real number. If the string does
2178 not contain numeric expression, 0.0 is returned.
2179 This function is equivalent to `atof' except that it does
2180 not depend on the locale.
2181 The function `tcregexmatch' is used in order to check whether a string
2183 matches a regular expression.
2184 bool tcregexmatch(const char *str, const char *regex);
2186 `str' specifies the target string.
2187 `regex' specifies the regular expression string. If it
2188 begins with `*', the trailing substring is used as a
2189 case-insensitive regular expression.
2190 The return value is true if matching is success, else, it
2191 is false.
2192 The function `tcregexreplace' is used in order to replace each sub‐
2194 string matching a regular expression string.
2195 char *tcregexreplace(const char *str, const char *regex, const
2197 char *alt);
2198 `str' specifies the target string.
2199 `regex' specifies the regular expression string for sub‐
2200 strings. If it begins with `*', the trailing substring
2201 is used as a case-insensitive regular expression.
2202 `alt' specifies the alternative string with which each
2203 substrings is replaced. Each `&' in the string is
2204 replaced with the matched substring. Each `´ in the
2205 string escapes the following character. Special escapes
2206 "1" through "9" referring to the corresponding matching
2207 sub-expressions in the regular expression string are sup‐
2208 ported.
2209 The return value is a new converted string. Even if the
2210 regular expression is invalid, a copy of the original
2211 string is returned.
2212 Because the region of the return value is allocated with
2213 the `malloc' call, it should be released with the `free'
2214 call when it is no longer in use.
2215 The function `tcmd5hash' is used in order to get the MD5 hash value of
2217 a serial object.
2218 void tcmd5hash(const void *ptr, int size, char *buf);
2220 `ptr' specifies the pointer to the region.
2221 `size' specifies the size of the region.
2222 `buf' specifies the pointer to the region into which the
2223 result string is written. The size of the buffer should
2224 be equal to or more than 48 bytes.
2225 The function `tcarccipher' is used in order to cipher or decipher a
2227 serial object with the Arcfour stream cipher.
2228 void tcarccipher(const void *ptr, int size, const void *kbuf,
2230 int ksiz, void *obuf);
2231 `ptr' specifies the pointer to the region.
2232 `size' specifies the size of the region.
2233 `kbuf' specifies the pointer to the region of the cipher
2234 key.
2235 `ksiz' specifies the size of the region of the cipher
2236 key.
2237 `obuf' specifies the pointer to the region into which the
2238 result data is written. The size of the buffer should be
2239 equal to or more than the input region.
2240 The function `tctime' is used in order to get the time of day in sec‐
2242 onds.
2243 double tctime(void);
2245 The return value is the time of day in seconds. The
2246 accuracy is in microseconds.
2247 The function `tccalendar' is used in order to get the Gregorian calen‐
2249 dar of a time.
2250 void tccalendar(int64_t t, int jl, int *yearp, int *monp, int
2252 *dayp, int *hourp, int *minp, int *secp);
2253 `t' specifies the source time in seconds from the epoch.
2254 If it is `INT64_MAX', the current time is specified.
2255 `jl' specifies the jet lag of a location in seconds. If
2256 it is `INT_MAX', the local jet lag is specified.
2257 `yearp' specifies the pointer to a variable to which the
2258 year is assigned. If it is `NULL', it is not used.
2259 `monp' specifies the pointer to a variable to which the
2260 month is assigned. If it is `NULL', it is not used. 1
2261 means January and 12 means December.
2262 `dayp' specifies the pointer to a variable to which the
2263 day of the month is assigned. If it is `NULL', it is not
2264 used.
2265 `hourp' specifies the pointer to a variable to which the
2266 hours is assigned. If it is `NULL', it is not used.
2267 `minp' specifies the pointer to a variable to which the
2268 minutes is assigned. If it is `NULL', it is not used.
2269 `secp' specifies the pointer to a variable to which the
2270 seconds is assigned. If it is `NULL', it is not used.
2271 The function `tcdatestrwww' is used in order to format a date as a
2273 string in W3CDTF.
2274 void tcdatestrwww(int64_t t, int jl, char *buf);
2276 `t' specifies the source time in seconds from the epoch.
2277 If it is `INT64_MAX', the current time is specified.
2278 `jl' specifies the jet lag of a location in seconds. If
2279 it is `INT_MAX', the local jet lag is specified.
2280 `buf' specifies the pointer to the region into which the
2281 result string is written. The size of the buffer should
2282 be equal to or more than 48 bytes.
2283 W3CDTF represents a date as "YYYY-MM-DDThh:mm:ddTZD".
2284 The function `tcdatestrhttp' is used in order to format a date as a
2286 string in RFC 1123 format.
2287 void tcdatestrhttp(int64_t t, int jl, char *buf);
2289 `t' specifies the source time in seconds from the epoch.
2290 If it is `INT64_MAX', the current time is specified.
2291 `jl' specifies the jet lag of a location in seconds. If
2292 it is `INT_MAX', the local jet lag is specified.
2293 `buf' specifies the pointer to the region into which the
2294 result string is written. The size of the buffer should
2295 be equal to or more than 48 bytes.
2296 RFC 1123 format represents a date as "Wdy, DD-Mon-YYYY
2297 hh:mm:dd TZD".
2298 The function `tcstrmktime' is used in order to get the time value of a
2300 date string.
2301 int64_t tcstrmktime(const char *str);
2303 `str' specifies the date string in decimal, hexadecimal,
2304 W3CDTF, or RFC 822 (1123). Decimal can be trailed by "s"
2305 for in seconds, "m" for in minutes, "h" for in hours, and
2306 "d" for in days.
2307 The return value is the time value of the date or
2308 `INT64_MIN' if the format is invalid.
2309 The function `tcjetlag' is used in order to get the jet lag of the
2311 local time.
2312 int tcjetlag(void);
2314 The return value is the jet lag of the local time in sec‐
2315 onds.
2316 The function `tcdayofweek' is used in order to get the day of week of a
2318 date.
2319 int tcdayofweek(int year, int mon, int day);
2321 `year' specifies the year of a date.
2322 `mon' specifies the month of the date.
2323 `day' specifies the day of the date.
2324 The return value is the day of week of the date. 0 means
2325 Sunday and 6 means Saturday.
2326
2329 The function `tcrealpath' is used in order to get the canonicalized
2330 absolute path of a file.
2331 char *tcrealpath(const char *path);
2333 `path' specifies the path of the file.
2334 The return value is the canonicalized absolute path of a
2335 file, or `NULL' if the path is invalid.
2336 Because the region of the return value is allocated with
2337 the `malloc' call, it should be released with the `free'
2338 call when it is no longer in use.
2339 The function `tcstatfile' is used in order to get the status informa‐
2341 tion of a file.
2342 bool tcstatfile(const char *path, bool *isdirp, int64_t *sizep,
2344 int64_t *mtimep);
2345 `path' specifies the path of the file.
2346 `isdirp' specifies the pointer to a variable into which
2347 whether the file is a directory is assigned. If it is
2348 `NULL', it is ignored.
2349 `sizep' specifies the pointer to a variable into which
2350 the size of the file is assigned. If it is `NULL', it is
2351 ignored.
2352 `ntimep' specifies the pointer to a variable into which
2353 the size of the file is assigned. If it is `NULL', it is
2354 ignored.
2355 If successful, the return value is true, else, it is
2356 false.
2357 The function `tcreadfile' is used in order to read whole data of a
2359 file.
2360 void *tcreadfile(const char *path, int limit, int *sp);
2362 `path' specifies the path of the file. If it is `NULL',
2363 the standard input is specified.
2364 `limit' specifies the limiting size of reading data. If
2365 it is not more than 0, the limitation is not specified.
2366 `sp' specifies the pointer to the variable into which the
2367 size of the region of the return value is assigned. If
2368 it is `NULL', it is not used.
2369 The return value is the pointer to the allocated region
2370 of the read data, or `NULL' if the file could not be
2371 opened.
2372 Because an additional zero code is appended at the end of
2373 the region of the return value, the return value can be
2374 treated as a character string. Because the region of the
2375 return value is allocated with the `malloc' call, it
2376 should be released with the `free' call when when is no
2377 longer in use.
2378 The function `tcreadfilelines' is used in order to read every line of a
2380 file.
2381 TCLIST *tcreadfilelines(const char *path);
2383 `path' specifies the path of the file. If it is `NULL',
2384 the standard input is specified.
2385 The return value is a list object of every lines if suc‐
2386 cessful, else it is `NULL'.
2387 Line separators are cut out. Because the object of the
2388 return value is created with the function `tclistnew', it
2389 should be deleted with the function `tclistdel' when it
2390 is no longer in use.
2391 The function `tcwritefile' is used in order to write data into a file.
2393 bool tcwritefile(const char *path, const void *ptr, int size);
2395 `path' specifies the path of the file. If it is `NULL',
2396 the standard output is specified.
2397 `ptr' specifies the pointer to the data region.
2398 `size' specifies the size of the region.
2399 If successful, the return value is true, else, it is
2400 false.
2401 The function `tccopyfile' is used in order to copy a file.
2403 bool tccopyfile(const char *src, const char *dest);
2405 `src' specifies the path of the source file.
2406 `dest' specifies the path of the destination file.
2407 The return value is true if successful, else, it is
2408 false.
2409 If the destination file exists, it is overwritten.
2410 The function `tcreaddir' is used in order to read names of files in a
2412 directory.
2413 TCLIST *tcreaddir(const char *path);
2415 `path' specifies the path of the directory.
2416 The return value is a list object of names if successful,
2417 else it is `NULL'.
2418 Links to the directory itself and to the parent directory
2419 are ignored.
2420 Because the object of the return value is created with
2421 the function `tclistnew', it should be deleted with the
2422 function `tclistdel' when it is no longer in use.
2423 The function `tcglobpat' is used in order to expand a pattern into a
2425 list of matched paths.
2426 TCLIST *tcglobpat(const char *pattern);
2428 `pattern' specifies the matching pattern.
2429 The return value is a list object of matched paths. If
2430 no path is matched, an empty list is returned.
2431 Because the object of the return value is created with
2432 the function `tclistnew', it should be deleted with the
2433 function `tclistdel' when it is no longer in use.
2434 The function `tcremovelink' is used in order to remove a file or a
2436 directory and its sub ones recursively.
2437 bool tcremovelink(const char *path);
2439 `path' specifies the path of the link.
2440 If successful, the return value is true, else, it is
2441 false. False is returned when the link does not exist or
2442 the permission is denied.
2443 The function `tcwrite' is used in order to write data into a file.
2445 bool tcwrite(int fd, const void *buf, size_t size);
2447 `fd' specifies the file descriptor.
2448 `buf' specifies the buffer to be written.
2449 `size' specifies the size of the buffer.
2450 The return value is true if successful, else, it is
2451 false.
2452 The function `tcread' is used in order to read data from a file.
2454 bool tcread(int fd, void *buf, size_t size);
2456 `fd' specifies the file descriptor.
2457 `buf' specifies the buffer to store into.
2458 `size' specifies the size of the buffer.
2459 The return value is true if successful, else, it is
2460 false.
2461 The function `tclock' is used in order to lock a file.
2463 bool tclock(int fd, bool ex, bool nb);
2465 `fd' specifies the file descriptor.
2466 `ex' specifies whether an exclusive lock or a shared lock
2467 is performed.
2468 `nb' specifies whether to request with non-blocking.
2469 The return value is true if successful, else, it is
2470 false.
2471 The function `tcunlock' is used in order to unlock a file.
2473 bool tcunlock(int fd);
2475 `fd' specifies the file descriptor.
2476 The return value is true if successful, else, it is
2477 false.
2478 The function `tcsystem' is used in order to execute a shell command.
2480 int tcsystem(const char **args, int anum);
2482 `args' specifies an array of the command name and its
2483 arguments.
2484 `anum' specifies the number of elements of the array.
2485 The return value is the exit code of the command or
2486 `INT_MAX' on failure.
2487 The command name and the arguments are quoted and meta
2488 characters are escaped.
2489
2492 The function `tcurlencode' is used in order to encode a serial object
2493 with URL encoding.
2494 char *tcurlencode(const char *ptr, int size);
2496 `ptr' specifies the pointer to the region.
2497 `size' specifies the size of the region.
2498 The return value is the result string.
2499 Because the region of the return value is allocated with
2500 the `malloc' call, it should be released with the `free'
2501 call if when is no longer in use.
2502 The function `tcurldecode' is used in order to decode a string encoded
2504 with URL encoding.
2505 char *tcurldecode(const char *str, int *sp);
2507 `str' specifies the encoded string.
2508 `sp' specifies the pointer to a variable into which the
2509 size of the region of the return value is assigned.
2510 The return value is the pointer to the region of the
2511 result.
2512 Because an additional zero code is appended at the end of
2513 the region of the return value, the return value can be
2514 treated as a character string. Because the region of the
2515 return value is allocated with the `malloc' call, it
2516 should be released with the `free' call when it is no
2517 longer in use.
2518 The function `tcurlbreak' is used in order to break up a URL into ele‐
2520 ments.
2521 TCMAP *tcurlbreak(const char *str);
2523 `str' specifies the URL string.
2524 The return value is the map object whose keys are the
2525 name of elements. The key "self" indicates the URL
2526 itself. The key "scheme" indicates the scheme. The key
2527 "host" indicates the host of the server. The key "port"
2528 indicates the port number of the server. The key
2529 "authority" indicates the authority information. The key
2530 "path" indicates the path of the resource. The key
2531 "file" indicates the file name without the directory sec‐
2532 tion. The key "query" indicates the query string. The
2533 key "fragment" indicates the fragment string.
2534 Supported schema are HTTP, HTTPS, FTP, and FILE. Abso‐
2535 lute URL and relative URL are supported. Because the
2536 object of the return value is created with the function
2537 `tcmapnew', it should be deleted with the function
2538 `tcmapdel' when it is no longer in use.
2539 The function `tcurlresolve' is used in order to resolve a relative URL
2541 with an absolute URL.
2542 char *tcurlresolve(const char *base, const char *target);
2544 `base' specifies the absolute URL of the base location.
2545 `target' specifies the URL to be resolved.
2546 The return value is the resolved URL. If the target URL
2547 is relative, a new URL of relative location from the base
2548 location is returned. Else, a copy of the target URL is
2549 returned.
2550 Because the region of the return value is allocated with
2551 the `malloc' call, it should be released with the `free'
2552 call when it is no longer in use.
2553 The function `tcbaseencode' is used in order to encode a serial object
2555 with Base64 encoding.
2556 char *tcbaseencode(const char *ptr, int size);
2558 `ptr' specifies the pointer to the region.
2559 `size' specifies the size of the region.
2560 The return value is the result string.
2561 Because the region of the return value is allocated with
2562 the `malloc' call, it should be released with the `free'
2563 call if when is no longer in use.
2564 The function `tcbasedecode' is used in order to decode a string encoded
2566 with Base64 encoding.
2567 char *tcbasedecode(const char *str, int *sp);
2569 `str' specifies the encoded string.
2570 `sp' specifies the pointer to a variable into which the
2571 size of the region of the return value is assigned.
2572 The return value is the pointer to the region of the
2573 result.
2574 Because an additional zero code is appended at the end of
2575 the region of the return value, the return value can be
2576 treated as a character string. Because the region of the
2577 return value is allocated with the `malloc' call, it
2578 should be released with the `free' call when it is no
2579 longer in use.
2580 The function `tcquoteencode' is used in order to encode a serial object
2582 with Quoted-printable encoding.
2583 char *tcquoteencode(const char *ptr, int size);
2585 `ptr' specifies the pointer to the region.
2586 `size' specifies the size of the region.
2587 The return value is the result string.
2588 Because the region of the return value is allocated with
2589 the `malloc' call, it should be released with the `free'
2590 call if when is no longer in use.
2591 The function `tcquotedecode' is used in order to decode a string
2593 encoded with Quoted-printable encoding.
2594 char *tcquotedecode(const char *str, int *sp);
2596 `str' specifies the encoded string.
2597 `sp' specifies the pointer to a variable into which the
2598 size of the region of the return value is assigned.
2599 The return value is the pointer to the region of the
2600 result.
2601 Because an additional zero code is appended at the end of
2602 the region of the return value, the return value can be
2603 treated as a character string. Because the region of the
2604 return value is allocated with the `malloc' call, it
2605 should be released with the `free' call when it is no
2606 longer in use.
2607 The function `tcmimeencode' is used in order to encode a string with
2609 MIME encoding.
2610 char *tcmimeencode(const char *str, const char *encname, bool
2612 base);
2613 `str' specifies the string.
2614 `encname' specifies the string of the name of the charac‐
2615 ter encoding.
2616 `base' specifies whether to use Base64 encoding. If it
2617 is false, Quoted-printable is used.
2618 The return value is the result string.
2619 Because the region of the return value is allocated with
2620 the `malloc' call, it should be released with the `free'
2621 call when it is no longer in use.
2622 The function `tcmimedecode' is used in order to decode a string encoded
2624 with MIME encoding.
2625 char *tcmimedecode(const char *str, char *enp);
2627 `str' specifies the encoded string.
2628 `enp' specifies the pointer to the region into which the
2629 name of encoding is written. If it is `NULL', it is not
2630 used. The size of the buffer should be equal to or more
2631 than 32 bytes.
2632 The return value is the result string.
2633 Because the region of the return value is allocated with
2634 the `malloc' call, it should be released with the `free'
2635 call when it is no longer in use.
2636 The function `tcmimebreak' is used in order to split a string of MIME
2638 into headers and the body.
2639 char *tcmimebreak(const char *ptr, int size, TCMAP *headers, int
2641 *sp);
2642 `ptr' specifies the pointer to the region of MIME data.
2643 `size' specifies the size of the region.
2644 `headers' specifies a map object to store headers. If it
2645 is `NULL', it is not used. Each key of the map is an
2646 uncapitalized header name.
2647 `sp' specifies the pointer to the variable into which the
2648 size of the region of the return value is assigned.
2649 The return value is the pointer to the region of the body
2650 data.
2651 If the content type is defined, the header map has the
2652 key "TYPE" specifying the type. If the character encod‐
2653 ing is defined, the key "CHARSET" indicates the encoding
2654 name. If the boundary string of multipart is defined,
2655 the key "BOUNDARY" indicates the string. If the content
2656 disposition is defined, the key "DISPOSITION" indicates
2657 the direction. If the file name is defined, the key
2658 "FILENAME" indicates the name. If the attribute name is
2659 defined, the key "NAME" indicates the name. Because the
2660 region of the return value is allocated with the `malloc'
2661 call, it should be released with the `free' call when it
2662 is no longer in use.
2663 The function `tcmimeparts' is used in order to split multipart data of
2665 MIME into its parts.
2666 TCLIST *tcmimeparts(const char *ptr, int size, const char
2668 *boundary);
2669 `ptr' specifies the pointer to the region of multipart
2670 data of MIME.
2671 `size' specifies the size of the region.
2672 `boundary' specifies the boundary string.
2673 The return value is a list object. Each element of the
2674 list is the data of a part.
2675 Because the object of the return value is created with
2676 the function `tclistnew', it should be deleted with the
2677 function `tclistdel' when it is no longer in use.
2678 The function `tchexencode' is used in order to encode a serial object
2680 with hexadecimal encoding.
2681 char *tchexencode(const char *ptr, int size);
2683 `ptr' specifies the pointer to the region.
2684 `size' specifies the size of the region.
2685 The return value is the result string.
2686 Because the region of the return value is allocated with
2687 the `malloc' call, it should be released with the `free'
2688 call if when is no longer in use.
2689 The function `tchexdecode' is used in order to decode a string encoded
2691 with hexadecimal encoding.
2692 char *tchexdecode(const char *str, int *sp);
2694 `str' specifies the encoded string.
2695 `sp' specifies the pointer to a variable into which the
2696 size of the region of the return
2697 value is assigned.
2698 The return value is the pointer to the region of the
2699 result.
2700 Because an additional zero code is appended at the end of
2701 the region of the return value, the return value can be
2702 treated as a character string. Because the region of the
2703 return value is allocated with the `malloc' call, it
2704 should be released with the `free' call when it is no
2705 longer in use.
2706 The function `tcpackencode' is used in order to compress a serial
2708 object with Packbits encoding.
2709 char *tcpackencode(const char *ptr, int size, int *sp);
2711 `ptr' specifies the pointer to the region.
2712 `size' specifies the size of the region.
2713 `sp' specifies the pointer to the variable into which the
2714 size of the region of the return value is assigned.
2715 If successful, the return value is the pointer to the
2716 result object, else, it is `NULL'.
2717 Because the region of the return value is allocated with
2718 the `malloc' call, it should be released with the `free'
2719 call when it is no longer in use.
2720 The function `tcpackdecode' is used in order to decompress a serial
2722 object compressed with Packbits encoding.
2723 char *tcpackdecode(const char *ptr, int size, int *sp);
2725 `ptr' specifies the pointer to the region.
2726 `size' specifies the size of the region.
2727 `sp' specifies the pointer to a variable into which the
2728 size of the region of the return value is assigned.
2729 If successful, the return value is the pointer to the
2730 result object, else, it is `NULL'.
2731 Because an additional zero code is appended at the end of
2732 the region of the return value, the return value can be
2733 treated as a character string. Because the region of the
2734 return value is allocated with the `malloc' call, it
2735 should be released with the `free' call when it is no
2736 longer in use.
2737 The function `tcbsencode' is used in order to compress a serial object
2739 with TCBS encoding.
2740 char *tcbsencode(const char *ptr, int size, int *sp);
2742 `ptr' specifies the pointer to the region.
2743 `size' specifies the size of the region.
2744 `sp' specifies the pointer to the variable into which the
2745 size of the region of the return value is assigned.
2746 If successful, the return value is the pointer to the
2747 result object, else, it is `NULL'.
2748 Because the region of the return value is allocated with
2749 the `malloc' call, it should be released with the `free'
2750 call when it is no longer in use.
2751 The function `tcbsdecode' is used in order to decompress a serial
2753 object compressed with TCBS encoding.
2754 char *tcbsdecode(const char *ptr, int size, int *sp);
2756 `ptr' specifies the pointer to the region.
2757 `size' specifies the size of the region.
2758 `sp' specifies the pointer to a variable into which the
2759 size of the region of the return value is assigned.
2760 If successful, the return value is the pointer to the
2761 result object, else, it is `NULL'.
2762 Because an additional zero code is appended at the end of
2763 the region of the return value, the return value can be
2764 treated as a character string. Because the region of the
2765 return value is allocated with the `malloc' call, it
2766 should be released with the `free' call when it is no
2767 longer in use.
2768 The function `tcdeflate' is used in order to compress a serial object
2770 with Deflate encoding.
2771 char *tcdeflate(const char *ptr, int size, int *sp);
2773 `ptr' specifies the pointer to the region.
2774 `size' specifies the size of the region.
2775 `sp' specifies the pointer to the variable into which the
2776 size of the region of the return value is assigned.
2777 If successful, the return value is the pointer to the
2778 result object, else, it is `NULL'.
2779 Because the region of the return value is allocated with
2780 the `malloc' call, it should be released with the `free'
2781 call when it is no longer in use.
2782 The function `tcinflate' is used in order to decompress a serial object
2784 compressed with Deflate encoding.
2785 char *tcinflate(const char *ptr, int size, int *sp);
2787 `ptr' specifies the pointer to the region.
2788 `size' specifies the size of the region.
2789 `sp' specifies the pointer to a variable into which the
2790 size of the region of the return value is assigned.
2791 If successful, the return value is the pointer to the
2792 result object, else, it is `NULL'.
2793 Because an additional zero code is appended at the end of
2794 the region of the return value, the return value can be
2795 treated as a character string. Because the region of the
2796 return value is allocated with the `malloc' call, it
2797 should be released with the `free' call when it is no
2798 longer in use.
2799 The function `tcgzipencode' is used in order to compress a serial
2801 object with GZIP encoding.
2802 char *tcgzipencode(const char *ptr, int size, int *sp);
2804 `ptr' specifies the pointer to the region.
2805 `size' specifies the size of the region.
2806 `sp' specifies the pointer to the variable into which the
2807 size of the region of the return value is assigned.
2808 If successful, the return value is the pointer to the
2809 result object, else, it is `NULL'.
2810 Because the region of the return value is allocated with
2811 the `malloc' call, it should be released with the `free'
2812 call when it is no longer in use.
2813 The function `tcgzipdecode' is used in order to decompress a serial
2815 object compressed with GZIP encoding.
2816 char *tcgzipdecode(const char *ptr, int size, int *sp);
2818 `ptr' specifies the pointer to the region.
2819 `size' specifies the size of the region.
2820 `sp' specifies the pointer to a variable into which the
2821 size of the region of the return value is assigned.
2822 If successful, the return value is the pointer to the
2823 result object, else, it is `NULL'.
2824 Because an additional zero code is appended at the end of
2825 the region of the return value, the return value can be
2826 treated as a character string. Because the region of the
2827 return value is allocated with the `malloc' call, it
2828 should be released with the `free' call when it is no
2829 longer in use.
2830 The function `tcgetcrc' is used in order to get the CRC32 checksum of a
2832 serial object.
2833 unsigned int tcgetcrc(const char *ptr, int size);
2835 `ptr' specifies the pointer to the region.
2836 `size' specifies the size of the region.
2837 The return value is the CRC32 checksum of the object.
2838 The function `tcbzipencode' is used in order to compress a serial
2840 object with BZIP2 encoding.
2841 char *tcbzipencode(const char *ptr, int size, int *sp);
2843 `ptr' specifies the pointer to the region.
2844 `size' specifies the size of the region.
2845 `sp' specifies the pointer to the variable into which the
2846 size of the region of the return value is assigned.
2847 If successful, the return value is the pointer to the
2848 result object, else, it is `NULL'.
2849 Because the region of the return value is allocated with
2850 the `malloc' call, it should be released with the `free'
2851 call when it is no longer in use.
2852 The function `tcbzipdecode' is used in order to decompress a serial
2854 object compressed with BZIP2 encoding.
2855 char *tcbzipdecode(const char *ptr, int size, int *sp);
2857 `ptr' specifies the pointer to the region.
2858 `size' specifies the size of the region.
2859 `sp' specifies the pointer to a variable into which the
2860 size of the region of the return value is assigned.
2861 If successful, the return value is the pointer to the
2862 result object, else, it is `NULL'.
2863 Because an additional zero code is appended at the end of
2864 the region of the return value, the return value can be
2865 treated as a character string. Because the region of the
2866 return value is allocated with the `malloc' call, it
2867 should be released with the `free' call when it is no
2868 longer in use.
2869 The function `tcberencode' is used in order to encode an array of non‐
2871 negative integers with BER encoding.
2872 char *tcberencode(const unsigned int *ary, int anum, int *sp);
2874 `ary' specifies the pointer to the array of nonnegative
2875 integers.
2876 `anum' specifies the size of the array.
2877 `sp' specifies the pointer to a variable into which the
2878 size of the region of the return value is assigned.
2879 The return value is the pointer to the region of the
2880 result.
2881 Because the region of the return value is allocated with
2882 the `malloc' call, it should be released with the `free'
2883 call if when is no longer in use.
2884 The function `tcberdecode' is used in order to decode a serial object
2886 encoded with BER encoding.
2887 unsigned int *tcberdecode(const char *ptr, int size, int *np);
2889 `ptr' specifies the pointer to the region.
2890 `size' specifies the size of the region.
2891 `np' specifies the pointer to a variable into which the
2892 number of elements of the return value is assigned.
2893 The return value is the pointer to the array of the
2894 result.
2895 Because the region of the return value is allocated with
2896 the `malloc' call, it should be released with the `free'
2897 call if when is no longer in use.
2898 The function `tcxmlescape' is used in order to escape meta characters
2900 in a string with the entity references of XML.
2901 char *tcxmlescape(const char *str);
2903 `str' specifies the string.
2904 The return value is the pointer to the escaped string.
2905 This function escapes only `&', `<', `>', and `"'.
2906 Because the region of the return value is allocated with
2907 the `malloc' call, it should be released with the `free'
2908 call when it is no longer in use.
2909 The function `tcxmlunescape' is used in order to unescape entity refer‐
2911 ences in a string of XML.
2912 char *tcxmlunescape(const char *str);
2914 `str' specifies the string.
2915 The return value is the unescaped string.
2916 This function restores only `&', `<', `>', and
2917 `"'. Because the region of the return value is
2918 allocated with the `malloc' call, it should be released
2919 with the `free' call when it is no longer in use.
2920
2923 tcutest(1), tcucodec(1), tokyocabinet(3)
2924Man Page 2012-08-18 TCUTIL(3)