Provided by: libtokyocabinet-dev_1.4.48-15.1build1_amd64 bug

NAME

       tcutil - the utility API

DESCRIPTION

       The  utility  API  is  a  set of routines to handle records on memory easily.  Especially,
       extensible string, array list, hash map, and ordered tree are useful.

       To use the utility API, include `tcutil.h' and related standard  header  files.   Usually,
       write the following description near the front of a source file.

              #include <tcutil.h>
              #include <stdlib.h>
              #include <time.h>
              #include <stdbool.h>
              #include <stdint.h>

       Objects  whose  type is pointer to `TCXSTR' are used for extensible string.  An extensible
       string object is created with the function `tcxstrnew' and is deleted  with  the  function
       `tcxstrdel'.   Objects  whose type is pointer to `TCLIST' are used for array list.  A list
       object is created  with  the  function  `tclistnew'  and  is  deleted  with  the  function
       `tclistdel'.   Objects  whose  type  is  pointer  to `TCMAP' are used for hash map.  A map
       object is  created  with  the  function  `tcmapnew'  and  is  deleted  with  the  function
       `tcmapdel'.   Objects whose type is pointer to `TCTREE' are used for ordered tree.  A tree
       object is created  with  the  function  `tctreenew'  and  is  deleted  with  the  function
       `tctreedel'.   To  avoid memory leak, it is important to delete every object when it is no
       longer in use.

API OF BASIC UTILITIES

       The constant `tcversion' is the string containing the version information.

              extern const char *tcversion;

       The variable `tcfatalfunc' is the pointer to the call back function for handling  a  fatal
       error.

              extern void (*tcfatalfunc)(const char *);
                     The argument specifies the error message.
                     The  initial  value of this variable is `NULL'.  If the value is `NULL', the
                     default function is called when a fatal error occurs.  A fatal error  occurs
                     when memory allocation is failed.

       The function `tcmalloc' is used in order to allocate a region on memory.

              void *tcmalloc(size_t size);
                     `size' specifies the size of the region.
                     The return value is the pointer to the allocated region.
                     This  function handles failure of memory allocation implicitly.  Because the
                     region of the return value is allocated with the `malloc' call, it should be
                     released with the `free' call when it is no longer in use.

       The function `tccalloc' is used in order to allocate a nullified region on memory.

              void *tccalloc(size_t nmemb, size_t size);
                     `nmemb' specifies the number of elements.
                     `size' specifies the size of each element.
                     The return value is the pointer to the allocated nullified region.
                     This  function handles failure of memory allocation implicitly.  Because the
                     region of the return value is allocated with the `calloc' call, it should be
                     released with the `free' call when it is no longer in use.

       The function `tcrealloc' is used in order to re-allocate a region on memory.

              void *tcrealloc(void *ptr, size_t size);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     The return value is the pointer to the re-allocated region.
                     This  function handles failure of memory allocation implicitly.  Because the
                     region of the return value is allocated with the `realloc' call,  it  should
                     be released with the `free' call when it is no longer in use.

       The function `tcmemdup' is used in order to duplicate a region on memory.

              void *tcmemdup(const void *ptr, size_t size);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     The return value is the pointer to the allocated region of the duplicate.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcstrdup' is used in order to duplicate a string on memory.

              char *tcstrdup(const void *str);
                     `str' specifies the string.
                     The return value is the allocated string equivalent to the specified string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcfree' is used in order to free a region on memory.

              void tcfree(void *ptr);
                     `ptr'  specifies  the pointer to the region.  If it is `NULL', this function
                     has no effect.
                     Although this function is just a wrapper of `free' call, this is  useful  in
                     applications using another package of the `malloc' series.

API OF EXTENSIBLE STRING

       The function `tcxstrnew' is used in order to create an extensible string object.

              TCXSTR *tcxstrnew(void);
                     The return value is the new extensible string object.

       The  function  `tcxstrnew2'  is used in order to create an extensible string object from a
       character string.

              TCXSTR *tcxstrnew2(const char *str);
                     `str' specifies the string of the initial content.
                     The return  value  is  the  new  extensible  string  object  containing  the
                     specified string.

       The  function `tcxstrnew3' is used in order to create an extensible string object with the
       initial allocation size.

              TCXSTR *tcxstrnew3(int asiz);
                     `asiz' specifies the initial allocation size.
                     The return value is the new extensible string object.

       The function `tcxstrdup' is used in order to copy an extensible string object.

              TCXSTR *tcxstrdup(const TCXSTR *xstr);
                     `xstr' specifies the extensible string object.
                     The return value is the new  extensible  string  object  equivalent  to  the
                     specified object.

       The function `tcxstrdel' is used in order to delete an extensible string object.

              void tcxstrdel(TCXSTR *xstr);
                     `xstr' specifies the extensible string object.
                     Note that the deleted object and its derivatives can not be used anymore.

       The  function  `tcxstrcat'  is  used  in  order  to  concatenate a region to the end of an
       extensible string object.

              void tcxstrcat(TCXSTR *xstr, const void *ptr, int size);
                     `xstr' specifies the extensible string object.
                     `ptr' specifies the pointer to the region to be appended.
                     `size' specifies the size of the region.

       The function `tcxstrcat2' is used in order to concatenate a character string to the end of
       an extensible string object.

              void tcxstrcat2(TCXSTR *xstr, const char *str);
                     `xstr' specifies the extensible string object.
                     `str' specifies the string to be appended.

       The  function  `tcxstrptr'  is  used  in  order  to  get  the  pointer of the region of an
       extensible string object.

              const void *tcxstrptr(const TCXSTR *xstr);
                     `xstr' specifies the extensible string object.
                     The return value is the pointer of the region of the object.
                     Because an additional zero code is appended at the end of the region of  the
                     return value, the return value can be treated as a character string.

       The  function `tcxstrsize' is used in order to get the size of the region of an extensible
       string object.

              int tcxstrsize(const TCXSTR *xstr);
                     `xstr' specifies the extensible string object.
                     The return value is the size of the region of the object.

       The function `tcxstrclear' is used in order to clear an extensible string object.

              void tcxstrclear(TCXSTR *xstr);
                     `xstr' specifies the extensible string object.
                     The internal buffer of the object is cleared and the size is set zero.

       The function `tcxstrprintf'  is  used  in  order  to  perform  formatted  output  into  an
       extensible string object.

              void tcxstrprintf(TCXSTR *xstr, const char *format, ...);
                     `xstr' specifies the extensible string object.
                     `format'  specifies the printf-like format string.  The conversion character
                     `%' can be used with such flag characters as `s', `d', `o', `u',  `x',  `X',
                     `c', `e', `E', `f', `g', `G', `@', `?', `b', and `%'.  `@' works as with `s'
                     but escapes meta characters of XML.  `?' works as with `s' but escapes  meta
                     characters of URL.  `b' converts an integer to the string as binary numbers.
                     The other conversion character work as with each original.
                     The other arguments are used according to the format string.

       The function `tcsprintf' is used in order to allocate a formatted string on memory.

              char *tcsprintf(const char *format, ...);
                     `format' specifies the printf-like format string.  The conversion  character
                     `%'  can  be used with such flag characters as `s', `d', `o', `u', `x', `X',
                     `c', `e', `E', `f', `g', `G', `@', `?', `b', and `%'.  `@' works as with `s'
                     but  escapes meta characters of XML.  `?' works as with `s' but escapes meta
                     characters of URL.  `b' converts an integer to the string as binary numbers.
                     The other conversion character work as with each original.
                     The other arguments are used according to the format string.
                     The return value is the pointer to the region of the result string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

API OF ARRAY LIST

       The function `tclistnew' is used in order to create a list object.

              TCLIST *tclistnew(void);
                     The return value is the new list object.

       The function `tclistnew2' is used in order to create a  list  object  with  expecting  the
       number of elements.

              TCLIST *tclistnew2(int anum);
                     `anum' specifies the number of elements expected to be stored in the list.
                     The return value is the new list object.

       The  function  `tclistnew3'  is  used in order to create a list object with initial string
       elements.

              TCLIST *tclistnew3(const char *str, ...);
                     `str' specifies the string of the first element.
                     The other arguments are other elements.  They should be trailed by a  `NULL'
                     argument.
                     The return value is the new list object.

       The function `tclistdup' is used in order to copy a list object.

              TCLIST *tclistdup(const TCLIST *list);
                     `list' specifies the list object.
                     The return value is the new list object equivalent to the specified object.

       The function `tclistdel' is used in order to delete a list object.

              void tclistdel(TCLIST *list);
                     `list' specifies the list object.
                     Note that the deleted object and its derivatives can not be used anymore.

       The function `tclistnum' is used in order to get the number of elements of a list object.

              int tclistnum(const TCLIST *list);
                     `list' specifies the list object.
                     The return value is the number of elements of the list.

       The  function  `tclistval' is used in order to get the pointer to the region of an element
       of a list object.

              const void *tclistval(const TCLIST *list, int index, int *sp);
                     `list' specifies the list object.
                     `index' specifies the index of the element.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the value.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return value can be treated as  a  character  string.   If
                     `index' is equal to or more than the number of elements, the return value is
                     `NULL'.

       The function `tclistval2' is used in order to get the string  of  an  element  of  a  list
       object.

              const char *tclistval2(const TCLIST *list, int index);
                     `list' specifies the list object.
                     `index' specifies the index of the element.
                     The return value is the string of the value.
                     If `index' is equal to or more than the number of elements, the return value
                     is `NULL'.

       The function `tclistpush' is used in order to add an element at the end of a list object.

              void tclistpush(TCLIST *list, const void *ptr, int size);
                     `list' specifies the list object.
                     `ptr' specifies the pointer to the region of the new element.
                     `size' specifies the size of the region.

       The function `tclistpush2' is used in order to add a string element at the end of  a  list
       object.

              void tclistpush2(TCLIST *list, const char *str);
                     `list' specifies the list object.
                     `str' specifies the string of the new element.

       The  function  `tclistpop'  is  used  in  order  to remove an element of the end of a list
       object.

              void *tclistpop(TCLIST *list, int *sp);
                     `list' specifies the list object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the removed element.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.   If
                     the list is empty, the return value is `NULL'.

       The function `tclistpop2' is used in order to remove a string element of the end of a list
       object.

              char *tclistpop2(TCLIST *list);
                     `list' specifies the list object.
                     The return value is the string of the removed element.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it  should be released with the `free' call when it is no longer in use.  If
                     the list is empty, the return value is `NULL'.

       The function `tclistunshift' is used in order to add an element  at  the  top  of  a  list
       object.

              void tclistunshift(TCLIST *list, const void *ptr, int size);
                     `list' specifies the list object.
                     `ptr' specifies the pointer to the region of the new element.
                     `size' specifies the size of the region.

       The  function  `tclistunshift2'  is  used in order to add a string element at the top of a
       list object.

              void tclistunshift2(TCLIST *list, const char *str);
                     `list' specifies the list object.
                     `str' specifies the string of the new element.

       The function `tclistshift' is used in order to remove an element of  the  top  of  a  list
       object.

              void *tclistshift(TCLIST *list, int *sp);
                     `list' specifies the list object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the removed element.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it  should be released with the `free' call when it is no longer in use.  If
                     the list is empty, the return value is `NULL'.

       The function `tclistshift2' is used in order to remove a string element of the  top  of  a
       list object.

              char *tclistshift2(TCLIST *list);
                     `list' specifies the list object.
                     The return value is the string of the removed element.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.   If
                     the list is empty, the return value is `NULL'.

       The  function  `tclistinsert' is used in order to add an element at the specified location
       of a list object.

              void tclistinsert(TCLIST *list, int index, const void *ptr, int size);
                     `list' specifies the list object.
                     `index' specifies the index of the new element.
                     `ptr' specifies the pointer to the region of the new element.
                     `size' specifies the size of the region.
                     If `index' is equal to or more than the number of  elements,  this  function
                     has no effect.

       The  function  `tclistinsert2'  is  used in order to add a string element at the specified
       location of a list object.

              void tclistinsert2(TCLIST *list, int index, const char *str);
                     `list' specifies the list object.
                     `index' specifies the index of the new element.
                     `str' specifies the string of the new element.
                     If `index' is equal to or more than the number of  elements,  this  function
                     has no effect.

       The  function  `tclistremove'  is  used  in  order  to  remove an element at the specified
       location of a list object.

              void *tclistremove(TCLIST *list, int index, int *sp);
                     `list' specifies the list object.
                     `index' specifies the index of the element to be removed.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the removed element.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.   If
                     `index'  is  equal  to  or  more  than the number of elements, no element is
                     removed and the return value is `NULL'.

       The function `tclistremove2' is used in order to remove a string element at the  specified
       location of a list object.

              char *tclistremove2(TCLIST *list, int index);
                     `list' specifies the list object.
                     `index' specifies the index of the element to be removed.
                     The return value is the string of the removed element.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.   If
                     `index'  is  equal  to  or  more  than the number of elements, no element is
                     removed and the return value is `NULL'.

       The function `tclistover' is used in order  to  overwrite  an  element  at  the  specified
       location of a list object.

              void tclistover(TCLIST *list, int index, const void *ptr, int size);
                     `list' specifies the list object.
                     `index' specifies the index of the element to be overwritten.
                     `ptr' specifies the pointer to the region of the new content.
                     `size' specifies the size of the new content.
                     If  `index'  is  equal to or more than the number of elements, this function
                     has no effect.

       The function `tclistover2' is used in order to overwrite a string element at the specified
       location of a list object.

              void tclistover2(TCLIST *list, int index, const char *str);
                     `list' specifies the list object.
                     `index' specifies the index of the element to be overwritten.
                     `str' specifies the string of the new content.
                     If  `index'  is  equal to or more than the number of elements, this function
                     has no effect.

       The function `tclistsort' is used in order to sort elements of a list  object  in  lexical
       order.

              void tclistsort(TCLIST *list);
                     `list' specifies the list object.

       The function `tclistlsearch' is used in order to search a list object for an element using
       liner search.

              int tclistlsearch(const TCLIST *list, const void *ptr, int size);
                     `list' specifies the list object.
                     `ptr' specifies the pointer to the region of the key.
                     `size' specifies the size of the region.
                     The return value is the index of a corresponding element or -1 if  there  is
                     no corresponding element.
                     If two or more elements correspond, the former returns.

       The function `tclistbsearch' is used in order to search a list object for an element using
       binary search.

              int tclistbsearch(const TCLIST *list, const void *ptr, int size);
                     `list' specifies the list object.  It should be sorted in lexical order.
                     `ptr' specifies the pointer to the region of the key.
                     `size' specifies the size of the region.
                     The return value is the index of a corresponding element or -1 if  there  is
                     no corresponding element.
                     If two or more elements correspond, which returns is not defined.

       The function `tclistclear' is used in order to clear a list object.

              void tclistclear(TCLIST *list);
                     `list' specifies the list object.
                     All elements are removed.

       The function `tclistdump' is used in order to serialize a list object into a byte array.

              void *tclistdump(const TCLIST *list, int *sp);
                     `list' specifies the list object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the result serial region.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The  function `tclistload' is used in order to create a list object from a serialized byte
       array.

              TCLIST *tclistload(const void *ptr, int size);
                     `ptr' specifies the pointer to the region of serialized byte array.
                     `size' specifies the size of the region.
                     The return value is a new list object.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tclistnew',  it  should be deleted with the function `tclistdel' when it is
                     no longer in use.

API OF HASH MAP

       The function `tcmapnew' is used in order to create a map object.

              TCMAP *tcmapnew(void);
                     The return value is the new map object.

       The function `tcmapnew2' is used in order to create  a  map  object  with  specifying  the
       number of the buckets.

              TCMAP *tcmapnew2(uint32_t bnum);
                     `bnum' specifies the number of the buckets.
                     The return value is the new map object.

       The  function  `tcmapnew3'  is  used  in  order to create a map object with initial string
       elements.

              TCMAP *tcmapnew3(const char *str, ...);
                     `str' specifies the string of the first element.
                     The other arguments are other elements.  They should be trailed by a  `NULL'
                     argument.
                     The return value is the new map object.
                     The key and the value of each record are situated one after the other.

       The function `tcmapdup' is used in order to copy a map object.

              TCMAP *tcmapdup(const TCMAP *map);
                     `map' specifies the map object.
                     The return value is the new map object equivalent to the specified object.

       The function `tcmapdel' is used in order to delete a map object.

              void tcmapdel(TCMAP *map);
                     `map' specifies the map object.
                     Note that the deleted object and its derivatives can not be used anymore.

       The function `tcmapput' is used in order to store a record into a map object.

              void tcmapput(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
                     `map' specifies the map object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If a record with the same key exists in the map, it is overwritten.

       The function `tcmapput2' is used in order to store a string record into a map object.

              void tcmapput2(TCMAP *map, const char *kstr, const char *vstr);
                     `map' specifies the map object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If a record with the same key exists in the map, it is overwritten.

       The function `tcmapputkeep' is used in order to store a new record into a map object.

              bool  tcmapputkeep(TCMAP  *map,  const  void *kbuf, int ksiz, const void *vbuf, int
              vsiz);
                     `map' specifies the map object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If successful, the return value is true, else, it is false.
                     If a record with the same key exists  in  the  map,  this  function  has  no
                     effect.

       The  function  `tcmapputkeep2'  is  used  in order to store a new string record into a map
       object.

              bool tcmapputkeep2(TCMAP *map, const char *kstr, const char *vstr);
                     `map' specifies the map object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If successful, the return value is true, else, it is false.
                     If a record with the same key exists  in  the  map,  this  function  has  no
                     effect.

       The function `tcmapputcat' is used in order to concatenate a value at the end of the value
       of the existing record in a map object.

              void tcmapputcat(TCMAP *map, const void *kbuf, int  ksiz,  const  void  *vbuf,  int
              vsiz);
                     `map' specifies the map object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If there is no corresponding record, a new record is created.

       The  function  `tcmapputcat2' is used in order to concatenate a string value at the end of
       the value of the existing record in a map object.

              void tcmapputcat2(TCMAP *map, const char *kstr, const char *vstr);
                     `map' specifies the map object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If there is no corresponding record, a new record is created.

       The function `tcmapout' is used in order to remove a record of a map object.

              bool tcmapout(TCMAP *map, const void *kbuf, int ksiz);
                     `map' specifies the map object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     If successful, the return value is true.  False is returned when  no  record
                     corresponds to the specified key.

       The function `tcmapout2' is used in order to remove a string record of a map object.

              bool tcmapout2(TCMAP *map, const char *kstr);
                     `map' specifies the map object.
                     `kstr' specifies the string of the key.
                     If  successful,  the return value is true.  False is returned when no record
                     corresponds to the specified key.

       The function `tcmapget' is used in order to retrieve a record in a map object.

              const void *tcmapget(const TCMAP *map, const void *kbuf, int ksiz, int *sp);
                     `map' specifies the map object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the region of the value of
                     the corresponding record.  `NULL' is returned when no record corresponds.
                     Because an additional zero code is appended at the end of the region of  the
                     return value, the return value can be treated as a character string.

       The function `tcmapget2' is used in order to retrieve a string record in a map object.

              const char *tcmapget2(const TCMAP *map, const char *kstr);
                     `map' specifies the map object.
                     `kstr' specifies the string of the key.
                     If  successful,  the  return  value  is  the  string  of  the  value  of the
                     corresponding record.  `NULL' is returned when no record corresponds.

       The function `tcmapmove' is used in order to move a record to the edge of a map object.

              bool tcmapmove(TCMAP *map, const void *kbuf, int ksiz, bool head);
                     `map' specifies the map object.
                     `kbuf' specifies the pointer to the region of a key.
                     `ksiz' specifies the size of the region of the key.
                     `head' specifies the destination which is the head if it is true or the tail
                     if else.
                     If  successful,  the return value is true.  False is returned when no record
                     corresponds to the specified key.

       The function `tcmapmove2' is used in order to move a string record to the edge  of  a  map
       object.

              bool tcmapmove2(TCMAP *map, const char *kstr, bool head);
                     `map' specifies the map object.
                     `kstr' specifies the string of a key.
                     `head' specifies the destination which is the head if it is true or the tail
                     if else.
                     If successful, the return value is true.  False is returned when  no  record
                     corresponds to the specified key.

       The function `tcmapiterinit' is used in order to initialize the iterator of a map object.

              void tcmapiterinit(TCMAP *map);
                     `map' specifies the map object.
                     The  iterator  is  used in order to access the key of every record stored in
                     the map object.

       The function `tcmapiternext' is used in order to get the next key of the iterator of a map
       object.

              const void *tcmapiternext(TCMAP *map, int *sp);
                     `map' specifies the map object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the  region  of  the  next
                     key,  else,  it is `NULL'.  `NULL' is returned when no record can be fetched
                     from the iterator.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return value can be treated as a character string.  The
                     order of iteration is assured to be the same as the stored order.

       The function `tcmapiternext2' is used in order to get the next key string of the  iterator
       of a map object.

              const char *tcmapiternext2(TCMAP *map);
                     `map' specifies the map object.
                     If  successful,  the  return  value is the pointer to the region of the next
                     key, else, it is `NULL'.  `NULL' is returned when no record can  be  fetched
                     from the iterator.
                     The order of iteration is assured to be the same as the stored order.

       The  function  `tcmaprnum'  is  used in order to get the number of records stored in a map
       object.

              uint64_t tcmaprnum(const TCMAP *map);
                     `map' specifies the map object.
                     The return value is the number of the records stored in the map object.

       The function `tcmapmsiz' is used in order to get the total size of memory used  in  a  map
       object.

              uint64_t tcmapmsiz(const TCMAP *map);
                     `map' specifies the map object.
                     The return value is the total size of memory used in a map object.

       The function `tcmapkeys' is used in order to create a list object containing all keys in a
       map object.

              TCLIST *tcmapkeys(const TCMAP *map);
                     `map' specifies the map object.
                     The return value is the new list object  containing  all  keys  in  the  map
                     object.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tclistnew', it should be deleted with the function `tclistdel' when  it  is
                     no longer in use.

       The function `tcmapvals' is used in order to create a list object containing all values in
       a map object.

              TCLIST *tcmapvals(const TCMAP *map);
                     `map' specifies the map object.
                     The return value is the new list object containing all  values  in  the  map
                     object.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tclistnew', it should be deleted with the function `tclistdel' when  it  is
                     no longer in use.

       The function `tcmapaddint' is used in order to add an integer to a record in a map object.

              int tcmapaddint(TCMAP *map, const void *kbuf, int ksiz, int num);
                     `map' specifies the map object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     The return value is the summation value.
                     If  the  corresponding record exists, the value is treated as an integer and
                     is added to.  If no record corresponds, a new record of the additional value
                     is stored.

       The  function  `tcmapadddouble' is used in order to add a real number to a record in a map
       object.

              double tcmapadddouble(TCMAP *map, const void *kbuf, int ksiz, double num);
                     `map' specifies the map object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     The return value is the summation value.
                     If the corresponding record exists, the value is treated as  a  real  number
                     and  is  added to.  If no record corresponds, a new record of the additional
                     value is stored.

       The function `tcmapclear' is used in order to clear a map object.

              void tcmapclear(TCMAP *map);
                     `map' specifies the map object.
                     All records are removed.

       The function `tcmapcutfront' is used in order to remove front records of a map object.

              void tcmapcutfront(TCMAP *map, int num);
                     `map' specifies the map object.
                     `num' specifies the number of records to be removed.

       The function `tcmapdump' is used in order to serialize a map object into a byte array.

              void *tcmapdump(const TCMAP *map, int *sp);
                     `map' specifies the map object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the result serial region.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcmapload' is used in order to create a map object from  a  serialized  byte
       array.

              TCMAP *tcmapload(const void *ptr, int size);
                     `ptr' specifies the pointer to the region of serialized byte array.
                     `size' specifies the size of the region.
                     The return value is a new map object.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tcmapnew', it should be deleted with the function `tcmapdel' when it is  no
                     longer in use.

API OF ORDERED TREE

       The function `tctreenew' is used in order to create a tree object.

              TCTREE *tctreenew(void);
                     The return value is the new tree object.

       The  function  `tctreenew2'  is  used in order to create a tree object with specifying the
       custom comparison function.

              TCTREE *tctreenew2(TCCMP cmp, void *cmpop);
                     `cmp' specifies the pointer to the custom comparison function.  It  receives
                     five  parameters.   The  first parameter is the pointer to the region of one
                     key.  The second parameter is the size of the region of one key.  The  third
                     parameter  is  the  pointer  to  the  region  of  the other key.  The fourth
                     parameter is the size of the region of the other key.  The  fifth  parameter
                     is  the  pointer  to the optional opaque object.  It returns positive if the
                     former is big, negative if the latter is big, 0 if both are equivalent.
                     `cmpop' specifies an arbitrary pointer to be given as  a  parameter  of  the
                     comparison function.  If it is not needed, `NULL' can be specified.
                     The return value is the new tree object.
                     The  default  comparison  function  compares  keys of two records by lexical
                     order.    The   functions    `tccmplexical'    (default),    `tccmpdecimal',
                     `tccmpint32', and `tccmpint64' are built-in.

       The function `tctreedup' is used in order to copy a tree object.

              TCTREE *tctreedup(const TCTREE *tree);
                     `tree' specifies the tree object.
                     The return value is the new tree object equivalent to the specified object.

       The function `tctreedel' is used in order to delete a tree object.

              void tctreedel(TCTREE *tree);
                     `tree' specifies the tree object.
                     Note that the deleted object and its derivatives can not be used anymore.

       The function `tctreeput' is used in order to store a record into a tree object.

              void  tctreeput(TCTREE  *tree,  const  void  *kbuf, int ksiz, const void *vbuf, int
              vsiz);
                     `tree' specifies the tree object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If a record with the same key exists in the tree, it is overwritten.

       The function `tctreeput2' is used in order to store a string record into a tree object.

              void tctreeput2(TCTREE *tree, const char *kstr, const char *vstr);
                     `tree' specifies the tree object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If a record with the same key exists in the tree, it is overwritten.

       The function `tctreeputkeep' is used in order to store a new record into a tree object.

              bool tctreeputkeep(TCTREE *tree, const void *kbuf, int ksiz, const void *vbuf,  int
              vsiz);
                     `tree' specifies the tree object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If successful, the return value is true, else, it is false.
                     If  a  record  with  the  same  key exists in the tree, this function has no
                     effect.

       The function `tctreeputkeep2' is used in order to store a new string record  into  a  tree
       object.

              bool tctreeputkeep2(TCTREE *tree, const char *kstr, const char *vstr);
                     `tree' specifies the tree object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If successful, the return value is true, else, it is false.
                     If  a  record  with  the  same  key exists in the tree, this function has no
                     effect.

       The function `tctreeputcat' is used in order to concatenate a value  at  the  end  of  the
       value of the existing record in a tree object.

              void  tctreeputcat(TCTREE  *tree, const void *kbuf, int ksiz, const void *vbuf, int
              vsiz);
                     `tree' specifies the tree object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If there is no corresponding record, a new record is created.

       The function `tctreeputcat2' is used in order to concatenate a string value at the end  of
       the value of the existing record in a tree object.

              void tctreeputcat2(TCTREE *tree, const char *kstr, const char *vstr);
                     `tree' specifies the tree object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If there is no corresponding record, a new record is created.

       The function `tctreeout' is used in order to remove a record of a tree object.

              bool tctreeout(TCTREE *tree, const void *kbuf, int ksiz);
                     `tree' specifies the tree object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     If  successful,  the return value is true.  False is returned when no record
                     corresponds to the specified key.

       The function `tctreeout2' is used in order to remove a string record of a tree object.

              bool tctreeout2(TCTREE *tree, const char *kstr);
                     `tree' specifies the tree object.
                     `kstr' specifies the string of the key.
                     If successful, the return value is true.  False is returned when  no  record
                     corresponds to the specified key.

       The function `tctreeget' is used in order to retrieve a record in a tree object.

              const void *tctreeget(TCTREE *tree, const void *kbuf, int ksiz, int *sp);
                     `tree' specifies the tree object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the region of the value of
                     the corresponding record.  `NULL' is returned when no record corresponds.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return value can be treated as a character string.

       The function `tctreeget2' is used in order to retrieve a string record in a tree object.

              const char *tctreeget2(TCTREE *tree, const char *kstr);
                     `tree' specifies the tree object.
                     `kstr' specifies the string of the key.
                     If successful,  the  return  value  is  the  string  of  the  value  of  the
                     corresponding record.  `NULL' is returned when no record corresponds.

       The  function  `tctreeiterinit'  is  used  in  order  to initialize the iterator of a tree
       object.

              void tctreeiterinit(TCTREE *tree);
                     `tree' specifies the tree object.
                     The iterator is used in order to access the key of every  record  stored  in
                     the tree object.

       The  function  `tctreeiternext'  is used in order to get the next key of the iterator of a
       tree object.

              const void *tctreeiternext(TCTREE *tree, int *sp);
                     `tree' specifies the tree object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If  successful,  the  return  value is the pointer to the region of the next
                     key, else, it is `NULL'.  `NULL' is returned when no record can  be  fetched
                     from the iterator.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return value can be treated as a  character  string.   The
                     order of iteration is assured to be ascending of the keys.

       The function `tctreeiternext2' is used in order to get the next key string of the iterator
       of a tree object.

              const char *tctreeiternext2(TCTREE *tree);
                     `tree' specifies the tree object.
                     If successful, the return value is the pointer to the  region  of  the  next
                     key,  else,  it is `NULL'.  `NULL' is returned when no record can be fetched
                     from the iterator.
                     The order of iteration is assured to be ascending of the keys.

       The function `tctreernum' is used in order to get the number of records stored in  a  tree
       object.

              uint64_t tctreernum(const TCTREE *tree);
                     `tree' specifies the tree object.
                     The return value is the number of the records stored in the tree object.

       The  function `tctreemsiz' is used in order to get the total size of memory used in a tree
       object.

              uint64_t tctreemsiz(const TCTREE *tree);
                     `tree' specifies the tree object.
                     The return value is the total size of memory used in a tree object.

       The function `tctreekeys' is used in order to create a list object containing all keys  in
       a tree object.

              TCLIST *tctreekeys(const TCTREE *tree);
                     `tree' specifies the tree object.
                     The  return  value  is  the  new list object containing all keys in the tree
                     object.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tclistnew',  it  should be deleted with the function `tclistdel' when it is
                     no longer in use.

       The function `tctreevals' is used in order to create a list object containing  all  values
       in a tree object.

              TCLIST *tctreevals(const TCTREE *tree);
                     `tree' specifies the tree object.
                     The  return  value  is the new list object containing all values in the tree
                     object.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tclistnew',  it  should be deleted with the function `tclistdel' when it is
                     no longer in use.

       The function `tctreeaddint' is used in order to add an integer  to  a  record  in  a  tree
       object.

              int tctreeaddint(TCTREE *tree, const void *kbuf, int ksiz, int num);
                     `tree' specifies the tree object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     The return value is the summation value.
                     If  the  corresponding record exists, the value is treated as an integer and
                     is added to.  If no record corresponds, a new record of the additional value
                     is stored.

       The function `tctreeadddouble' is used in order to add a real number to a record in a tree
       object.

              double tctreeadddouble(TCTREE *tree, const void *kbuf, int ksiz, double num);
                     `tree' specifies the tree object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     The return value is the summation value.
                     If the corresponding record exists, the value is treated as  a  real  number
                     and  is  added to.  If no record corresponds, a new record of the additional
                     value is stored.

       The function `tctreeclear' is used in order to clear a tree object.

              void tctreeclear(TCTREE *tree);
                     `tree' specifies the tree object.
                     All records are removed.

       The function `tctreecutfringe' is used in order to remove fringe records of a tree object.

              void tctreecutfringe(TCTREE *tree, int num);
                     `tree' specifies the tree object.
                     `num' specifies the number of records to be removed.

       The function `tctreedump' is used in order to serialize a tree object into a byte array.

              void *tctreedump(const TCTREE *tree, int *sp);
                     `tree' specifies the tree object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the result serial region.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tctreeload' is used in order to create a tree object from a serialized  byte
       array.

              TCTREE *tctreeload(const void *ptr, int size, TCCMP cmp, void *cmpop);
                     `ptr' specifies the pointer to the region of serialized byte array.
                     `size' specifies the size of the region.
                     `cmp' specifies the pointer to the custom comparison function.
                     `cmpop'  specifies  an  arbitrary  pointer to be given as a parameter of the
                     comparison function.
                     If it is not needed, `NULL' can be specified.
                     The return value is a new tree object.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tctreenew',  it  should be deleted with the function `tctreedel' when it is
                     no longer in use.

API OF ON-MEMORY HASH DATABASE

       The function `tcmdbnew' is used in order to create an on-memory hash database object.

              TCMDB *tcmdbnew(void);
                     The return value is the new on-memory hash database object.
                     The object can be shared by plural threads because of the internal mutex.

       The function `tcmdbnew2' is used in order to create an on-memory hash database object with
       specifying the number of the buckets.

              TCMDB *tcmdbnew2(uint32_t bnum);
                     `bnum' specifies the number of the buckets.
                     The return value is the new on-memory hash database object.
                     The object can be shared by plural threads because of the internal mutex.

       The function `tcmdbdel' is used in order to delete an on-memory hash database object.

              void tcmdbdel(TCMDB *mdb);
                     `mdb' specifies the on-memory hash database object.

       The function `tcmdbput' is used in order to store a record into an on-memory hash database
       object.

              void tcmdbput(TCMDB *mdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
                     `mdb' specifies the on-memory hash database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If a record with the same key exists in the database, it is overwritten.

       The function `tcmdbput2' is used in order to store a string record into an on-memory  hash
       database object.

              void tcmdbput2(TCMDB *mdb, const char *kstr, const char *vstr);
                     `mdb' specifies the on-memory hash database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If a record with the same key exists in the database, it is overwritten.

       The  function `tcmdbputkeep' is used in order to store a new record into an on-memory hash
       database object.

              bool tcmdbputkeep(TCMDB *mdb, const void *kbuf, int ksiz,  const  void  *vbuf,  int
              vsiz);
                     `mdb' specifies the on-memory hash database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If successful, the return value is true, else, it is false.
                     If  a  record with the same key exists in the database, this function has no
                     effect.

       The function `tcmdbputkeep2' is used in order  to  store  a  new  string  record  into  an
       on-memory hash database object.

              bool tcmdbputkeep2(TCMDB *mdb, const char *kstr, const char *vstr);
                     `mdb' specifies the on-memory hash database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If successful, the return value is true, else, it is false.
                     If  a  record with the same key exists in the database, this function has no
                     effect.

       The function `tcmdbputcat' is used in order to concatenate a  value  at  the  end  of  the
       existing record in an on-memory hash database.

              void  tcmdbputcat(TCMDB  *mdb,  const  void  *kbuf, int ksiz, const void *vbuf, int
              vsiz);
                     `mdb' specifies the on-memory hash database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If there is no corresponding record, a new record is created.

       The function `tcmdbputcat2' is used in order to concatenate a string at  the  end  of  the
       existing record in an on-memory hash database.

              void tcmdbputcat2(TCMDB *mdb, const char *kstr, const char *vstr);
                     `mdb' specifies the on-memory hash database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If there is no corresponding record, a new record is created.

       The  function `tcmdbout' is used in order to remove a record of an on-memory hash database
       object.

              bool tcmdbout(TCMDB *mdb, const void *kbuf, int ksiz);
                     `mdb' specifies the on-memory hash database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     If successful, the return value is true.  False is returned when  no  record
                     corresponds to the specified key.

       The  function  `tcmdbout2' is used in order to remove a string record of an on-memory hash
       database object.

              bool tcmdbout2(TCMDB *mdb, const char *kstr);
                     `mdb' specifies the on-memory hash database object.
                     `kstr' specifies the string of the key.
                     If successful, the return value is true.  False is returned when  no  record
                     corresponds to the specified key.

       The  function  `tcmdbget'  is  used  in  order  to  retrieve a record in an on-memory hash
       database object.

              void *tcmdbget(TCMDB *mdb, const void *kbuf, int ksiz, int *sp);
                     `mdb' specifies the on-memory hash database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the region of the value of
                     the corresponding record.  `NULL' is returned when no record corresponds.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcmdbget2' is used in order to retrieve a string record in an on-memory hash
       database object.

              char *tcmdbget2(TCMDB *mdb, const char *kstr);
                     `mdb' specifies the on-memory hash database object.
                     `kstr' specifies the string of the key.
                     If successful,  the  return  value  is  the  string  of  the  value  of  the
                     corresponding record.  `NULL' is returned when no record corresponds.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcmdbvsiz' is used in order to get the size of the value of a record  in  an
       on-memory hash database object.

              int tcmdbvsiz(TCMDB *mdb, const void *kbuf, int ksiz);
                     `mdb' specifies the on-memory hash database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     If   successful,  the  return  value  is  the  size  of  the  value  of  the
                     corresponding record, else, it is -1.

       The function `tcmdbvsiz2' is used in order to get the size of the value of a string record
       in an on-memory hash database object.

              int tcmdbvsiz2(TCMDB *mdb, const char *kstr);
                     `mdb' specifies the on-memory hash database object.
                     `kstr' specifies the string of the key.
                     If   successful,  the  return  value  is  the  size  of  the  value  of  the
                     corresponding record, else, it is -1.

       The function `tcmdbiterinit' is used in order to initialize the iterator of  an  on-memory
       hash database object.

              void tcmdbiterinit(TCMDB *mdb);
                     `mdb' specifies the on-memory hash database object.
                     The  iterator  is  used in order to access the key of every record stored in
                     the on-memory hash database.

       The function `tcmdbiternext' is used in order to get the next key of the  iterator  of  an
       on-memory hash database object.

              void *tcmdbiternext(TCMDB *mdb, int *sp);
                     `mdb' specifies the on-memory hash database object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return
                     value is assigned.
                     If successful, the return value is the pointer to the  region  of  the  next
                     key,  else,  it is `NULL'.  `NULL' is returned when no record can be fetched
                     from the iterator.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.  The
                     order of iteration is assured to be the same as the stored order.

       The function `tcmdbiternext2' is used in order to get the next key string of the  iterator
       of an on-memory hash database object.

              char *tcmdbiternext2(TCMDB *mdb);
                     `mdb' specifies the on-memory hash database object.
                     If  successful,  the  return  value is the pointer to the region of the next
                     key, else, it is `NULL'.  `NULL' is returned when no record can  be  fetched
                     from the iterator.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.  The
                     order of iteration is assured to be the same as the stored order.

       The  function `tcmdbfwmkeys' is used in order to get forward matching keys in an on-memory
       hash database object.

              TCLIST *tcmdbfwmkeys(TCMDB *mdb, const void *pbuf, int psiz, int max);
                     `mdb' specifies the on-memory hash database object.
                     `pbuf' specifies the pointer to the region of the prefix.
                     `psiz' specifies the size of the region of the prefix.
                     `max' specifies the maximum  number  of  keys  to  be  fetched.   If  it  is
                     negative, no limit is specified.
                     The  return value is a list object of the corresponding keys.  This function
                     does never fail.  It returns an empty list even if no key corresponds.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tclistnew',  it  should be deleted with the function `tclistdel' when it is
                     no longer in use.  Note that this function may be very  slow  because  every
                     key in the database is scanned.

       The  function  `tcmdbfwmkeys2'  is used in order to get forward matching string keys in an
       on-memory hash database object.

              TCLIST *tcmdbfwmkeys2(TCMDB *mdb, const char *pstr, int max);
                     `mdb' specifies the on-memory hash database object.
                     `pstr' specifies the string of the prefix.
                     `max' specifies the maximum  number  of  keys  to  be  fetched.   If  it  is
                     negative, no limit is specified.
                     The  return value is a list object of the corresponding keys.  This function
                     does never fail.  It returns an empty list even if no key corresponds.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tclistnew',  it  should be deleted with the function `tclistdel' when it is
                     no longer in use.  Note that this function may be very  slow  because  every
                     key in the database is scanned.

       The  function  `tcmdbrnum'  is  used  in  order  to get the number of records stored in an
       on-memory hash database object.

              uint64_t tcmdbrnum(TCMDB *mdb);
                     `mdb' specifies the on-memory hash database object.
                     The return value is the number of the records stored in the database.

       The function `tcmdbmsiz' is used in order to get the total  size  of  memory  used  in  an
       on-memory hash database object.

              uint64_t tcmdbmsiz(TCMDB *mdb);
                     `mdb' specifies the on-memory hash database object.
                     The return value is the total size of memory used in the database.

       The  function `tcmdbaddint' is used in order to add an integer to a record in an on-memory
       hash database object.

              int tcmdbaddint(TCMDB *mdb, const void *kbuf, int ksiz, int num);
                     `mdb' specifies the on-memory hash database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     The return value is the summation value.
                     If the corresponding record exists, the value is treated as an  integer  and
                     is added to.  If no record corresponds, a new record of the additional value
                     is stored.

       The function `tcmdbadddouble' is used in order to add a real number  to  a  record  in  an
       on-memory hash database object.

              double tcmdbadddouble(TCMDB *mdb, const void *kbuf, int ksiz, double num);
                     `mdb' specifies the on-memory hash database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     The return value is the summation value.
                     If  the  corresponding  record exists, the value is treated as a real number
                     and is added to.  If no record corresponds, a new record of  the  additional
                     value is stored.

       The function `tcmdbvanish' is used in order to clear an on-memory hash database object.

              void tcmdbvanish(TCMDB *mdb);
                     `mdb' specifies the on-memory hash database object.
                     All records are removed.

       The function `tcmdbcutfront' is used in order to remove front records of an on-memory hash
       database object.

              void tcmdbcutfront(TCMDB *mdb, int num);
                     `mdb' specifies the on-memory hash database object.
                     `num' specifies the number of records to be removed.

API OF ON-MEMORY TREE DATABASE

       The function `tcndbnew' is used in order to create an on-memory tree database object.

              TCNDB *tcndbnew(void);
                     The return value is the new on-memory tree database object.
                     The object can be shared by plural threads because of the internal mutex.

       The function `tcndbnew2' is used in order to create an on-memory tree database object with
       specifying the custom comparison function.

              TCNDB *tcndbnew2(TCCMP cmp, void *cmpop);
                     `cmp' specifies the pointer to the custom comparison function.
                     `cmpop'  specifies  an  arbitrary  pointer to be given as a parameter of the
                     comparison function.  If it is not needed, `NULL' can be specified.
                     The return value is the new on-memory tree database object.
                     The default comparison function compares keys  of  two  records  by  lexical
                     order.     The    functions    `tccmplexical'   (default),   `tccmpdecimal',
                     `tccmpint32', and `tccmpint64' are built-in.  The object can  be  shared  by
                     plural threads because of the internal mutex.

       The function `tcndbdel' is used in order to delete an on-memory tree database object.

              void tcndbdel(TCNDB *ndb);
                     `ndb' specifies the on-memory tree database object.

       The function `tcndbput' is used in order to store a record into an on-memory tree database
       object.

              void tcndbput(TCNDB *ndb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
                     `ndb' specifies the on-memory tree database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If a record with the same key exists in the database, it is overwritten.

       The function `tcndbput2' is used in order to store a string record into an on-memory  tree
       database object.

              void tcndbput2(TCNDB *ndb, const char *kstr, const char *vstr);
                     `ndb' specifies the on-memory tree database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If a record with the same key exists in the database, it is overwritten.

       The  function `tcndbputkeep' is used in order to store a new record into an on-memory tree
       database object.

              bool tcndbputkeep(TCNDB *ndb, const void *kbuf, int ksiz,  const  void  *vbuf,  int
              vsiz);
                     `ndb' specifies the on-memory tree database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If successful, the return value is true, else, it is false.
                     If  a  record with the same key exists in the database, this function has no
                     effect.

       The function `tcndbputkeep2' is used in order  to  store  a  new  string  record  into  an
       on-memory tree database object.

              bool tcndbputkeep2(TCNDB *ndb, const char *kstr, const char *vstr);
                     `ndb' specifies the on-memory tree database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If successful, the return value is true, else, it is false.
                     If  a  record with the same key exists in the database, this function has no
                     effect.

       The function `tcndbputcat' is used in order to concatenate a  value  at  the  end  of  the
       existing record in an on-memory tree database.

              void  tcndbputcat(TCNDB  *ndb,  const  void  *kbuf, int ksiz, const void *vbuf, int
              vsiz);
                     `ndb' specifies the on-memory tree database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `vbuf' specifies the pointer to the region of the value.
                     `vsiz' specifies the size of the region of the value.
                     If there is no corresponding record, a new record is created.

       The function `tcndbputcat2' is used in order to concatenate a string at  the  end  of  the
       existing record in an on-memory tree database.

              void tcndbputcat2(TCNDB *ndb, const char *kstr, const char *vstr);
                     `ndb' specifies the on-memory tree database object.
                     `kstr' specifies the string of the key.
                     `vstr' specifies the string of the value.
                     If there is no corresponding record, a new record is created.

       The  function `tcndbout' is used in order to remove a record of an on-memory tree database
       object.

              bool tcndbout(TCNDB *ndb, const void *kbuf, int ksiz);
                     `ndb' specifies the on-memory tree database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     If successful, the return value is true.  False is returned when  no  record
                     corresponds to the specified key.

       The  function  `tcndbout2' is used in order to remove a string record of an on-memory tree
       database object.

              bool tcndbout2(TCNDB *ndb, const char *kstr);
                     `ndb' specifies the on-memory tree database object.
                     `kstr' specifies the string of the key.
                     If successful, the return value is true.  False is returned when  no  record
                     corresponds to the specified key.

       The  function  `tcndbget'  is  used  in  order  to  retrieve a record in an on-memory tree
       database object.

              void *tcndbget(TCNDB *ndb, const void *kbuf, int ksiz, int *sp);
                     `ndb' specifies the on-memory tree database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the region of the value of
                     the corresponding record.  `NULL' is returned when no record corresponds.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcndbget2' is used in order to retrieve a string record in an on-memory tree
       database object.

              char *tcndbget2(TCNDB *ndb, const char *kstr);
                     `ndb' specifies the on-memory tree database object.
                     `kstr' specifies the string of the key.
                     If successful,  the  return  value  is  the  string  of  the  value  of  the
                     corresponding record.  `NULL' is returned when no record corresponds.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcndbvsiz' is used in order to get the size of the value of a record  in  an
       on-memory tree database object.

              int tcndbvsiz(TCNDB *ndb, const void *kbuf, int ksiz);
                     `ndb' specifies the on-memory tree database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     If   successful,  the  return  value  is  the  size  of  the  value  of  the
                     corresponding record, else, it is -1.

       The function `tcndbvsiz2' is used in order to get the size of the value of a string record
       in an on-memory tree database object.

              int tcndbvsiz2(TCNDB *ndb, const char *kstr);
                     `ndb' specifies the on-memory tree database object.
                     `kstr' specifies the string of the key.
                     If   successful,  the  return  value  is  the  size  of  the  value  of  the
                     corresponding record, else, it is -1.

       The function `tcndbiterinit' is used in order to initialize the iterator of  an  on-memory
       tree database object.

              void tcndbiterinit(TCNDB *ndb);
                     `ndb' specifies the on-memory tree database object.
                     The  iterator  is  used in order to access the key of every record stored in
                     the on-memory database.

       The function `tcndbiternext' is used in order to get the next key of the  iterator  of  an
       on-memory tree database object.

              void *tcndbiternext(TCNDB *ndb, int *sp);
                     `ndb' specifies the on-memory tree database object.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the  region  of  the  next
                     key,  else,  it is `NULL'.  `NULL' is returned when no record can be fetched
                     from the iterator.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.  The
                     order of iteration is assured to be the same as the stored order.

       The function `tcndbiternext2' is used in order to get the next key string of the  iterator
       of an on-memory tree database object.

              char *tcndbiternext2(TCNDB *ndb);
                     `ndb' specifies the on-memory tree database object.
                     If  successful,  the  return  value is the pointer to the region of the next
                     key, else, it is `NULL'.  `NULL' is returned when no record can  be  fetched
                     from the iterator.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.  The
                     order of iteration is assured to be the same as the stored order.

       The  function `tcndbfwmkeys' is used in order to get forward matching keys in an on-memory
       tree database object.

              TCLIST *tcndbfwmkeys(TCNDB *ndb, const void *pbuf, int psiz, int max);
                     `ndb' specifies the on-memory tree database object.
                     `pbuf' specifies the pointer to the region of the prefix.
                     `psiz' specifies the size of the region of the prefix.
                     `max' specifies the maximum  number  of  keys  to  be  fetched.   If  it  is
                     negative, no limit is specified.
                     The  return value is a list object of the corresponding keys.  This function
                     does never fail.  It returns an empty list even if no key corresponds.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tclistnew',  it  should be deleted with the function `tclistdel' when it is
                     no longer in use.

       The function `tcndbfwmkeys2' is used in order to get forward matching string  keys  in  an
       on-memory tree database object.

              TCLIST *tcndbfwmkeys2(TCNDB *ndb, const char *pstr, int max);
                     `ndb' specifies the on-memory tree database object.
                     `pstr' specifies the string of the prefix.
                     `max'  specifies  the  maximum  number  of  keys  to  be  fetched.  If it is
                     negative, no limit is specified.
                     The return value is a list object of the corresponding keys.  This  function
                     does never fail.  It returns an empty list even if no key corresponds.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tclistnew', it should be deleted with the function `tclistdel' when  it  is
                     no longer in use.

       The  function  `tcndbrnum'  is  used  in  order  to get the number of records stored in an
       on-memory tree database object.

              uint64_t tcndbrnum(TCNDB *ndb);
                     `ndb' specifies the on-memory tree database object.
                     The return value is the number of the records stored in the database.

       The function `tcndbmsiz' is used in order to get the total  size  of  memory  used  in  an
       on-memory tree database object.

              uint64_t tcndbmsiz(TCNDB *ndb);
                     `ndb' specifies the on-memory tree database object.
                     The return value is the total size of memory used in the database.

       The  function `tcndbaddint' is used in order to add an integer to a record in an on-memory
       tree database object.

              int tcndbaddint(TCNDB *ndb, const void *kbuf, int ksiz, int num);
                     `ndb' specifies the on-memory tree database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     The return value is the summation value.
                     If the corresponding record exists, the value is treated as an  integer  and
                     is added to.  If no record corresponds, a new record of the additional value
                     is stored.

       The function `tcndbadddouble' is used in order to add a real number  to  a  record  in  an
       on-memory tree database object.

              double tcndbadddouble(TCNDB *ndb, const void *kbuf, int ksiz, double num);
                     `ndb' specifies the on-memory tree database object.
                     `kbuf' specifies the pointer to the region of the key.
                     `ksiz' specifies the size of the region of the key.
                     `num' specifies the additional value.
                     The return value is the summation value.
                     If  the  corresponding  record exists, the value is treated as a real number
                     and is added to.  If no record corresponds, a new record of  the  additional
                     value is stored.

       The function `tcndbvanish' is used in order to clear an on-memory tree database object.

              void tcndbvanish(TCNDB *ndb);
                     `ndb' specifies the on-memory tree database object.
                     All records are removed.

       The  function  `tcndbcutfringe'  is used in order to remove fringe records of an on-memory
       tree database object.

              void tcndbcutfringe(TCNDB *ndb, int num);
                     `ndb' specifies the on-memory tree database object.
                     `num' specifies the number of records to be removed.

API OF MEMORY POOL

       The function `tcmpoolnew' is used in order to create a memory pool object.

              TCMPOOL *tcmpoolnew(void);
                     The return value is the new memory pool object.

       The function `tcmpooldel' is used in order to delete a memory pool object.

              void tcmpooldel(TCMPOOL *mpool);
                     `mpool' specifies the memory pool object.
                     Note that the deleted object and its derivatives can not be used anymore.

       The function `tcmpoolpush' is used in order to relegate an arbitrary object  to  a  memory
       pool object.

              void *tcmpoolpush(TCMPOOL *mpool, void *ptr, void (*del)(void *));
                     `mpool' specifies the memory pool object.
                     `ptr' specifies the pointer to the object to be relegated.  If it is `NULL',
                     this function has no effect.
                     `del' specifies the pointer to the function to delete the object.
                     The return value is the pointer to the given object.
                     This function assures that the specified object is deleted when  the  memory
                     pool object is deleted.

       The function `tcmpoolpushptr' is used in order to relegate an allocated region to a memory
       pool object.

              void *tcmpoolpushptr(TCMPOOL *mpool, void *ptr);
                     `mpool' specifies the memory pool object.
                     `ptr' specifies the pointer to the region to be relegated.  If it is `NULL',
                     this function has no effect.
                     The return value is the pointer to the given object.
                     This  function assures that the specified region is released when the memory
                     pool object is deleted.

       The function `tcmpoolpushxstr' is used in order to relegate an extensible string object to
       a memory pool object.

              TCXSTR *tcmpoolpushxstr(TCMPOOL *mpool, TCXSTR *xstr);
                     `mpool' specifies the memory pool object.
                     `xstr'  specifies  the  extensible  string  object.   If  it is `NULL', this
                     function has no effect.
                     The return value is the pointer to the given object.
                     This function assures that the specified object is deleted when  the  memory
                     pool object is deleted.

       The function `tcmpoolpushlist' is used in order to relegate a list object to a memory pool
       object.

              TCLIST *tcmpoolpushlist(TCMPOOL *mpool, TCLIST *list);
                     `mpool' specifies the memory pool object.
                     `list' specifies the list object.  If it is `NULL',  this  function  has  no
                     effect.
                     The return value is the pointer to the given object.
                     This  function  assures that the specified object is deleted when the memory
                     pool object is deleted.

       The function `tcmpoolpushmap' is used in order to relegate a map object to a  memory  pool
       object.

              TCMAP *tcmpoolpushmap(TCMPOOL *mpool, TCMAP *map);
                     `mpool' specifies the memory pool object.
                     `map'  specifies  the  map  object.   If  it is `NULL', this function has no
                     effect.
                     The return value is the pointer to the given object.
                     This function assures that the specified object is deleted when  the  memory
                     pool object is deleted.

       The function `tcmpoolpushtree' is used in order to relegate a tree object to a memory pool
       object.

              TCTREE *tcmpoolpushtree(TCMPOOL *mpool, TCTREE *tree);
                     `mpool' specifies the memory pool object.
                     `tree' specifies the tree object.  If it is `NULL',  this  function  has  no
                     effect.
                     The return value is the pointer to the given object.
                     This  function  assures that the specified object is deleted when the memory
                     pool object is deleted.

       The function `tcmpoolmalloc' is used in order to allocate a region relegated to  a  memory
       pool object.

              void *tcmpoolmalloc(TCMPOOL *mpool, size_t size);
                     `mpool' specifies the memory pool object.
                     The  return  value  is  the pointer to the allocated region under the memory
                     pool.

       The function `tcmpoolxstrnew' is used in order  to  create  an  extensible  string  object
       relegated to a memory pool object.

              TCXSTR *tcmpoolxstrnew(TCMPOOL *mpool);
                     The return value is the new extensible string object under the memory pool.

       The  function  `tcmpoollistnew'  is  used  in order to create a list object relegated to a
       memory pool object.

              TCLIST *tcmpoollistnew(TCMPOOL *mpool);
                     The return value is the new list object under the memory pool.

       The function `tcmpoolmapnew' is used in order to create a map object relegated to a memory
       pool object.

              TCMAP *tcmpoolmapnew(TCMPOOL *mpool);
                     The return value is the new map object under the memory pool.

       The  function  `tcmpooltreenew'  is  used  in order to create a tree object relegated to a
       memory pool object.

              TCTREE *tcmpooltreenew(TCMPOOL *mpool);
                     The return value is the new tree object under the memory pool.

       The function `tcmpoolpop' is used in order to remove the most recently  installed  cleanup
       handler of a memory pool object.

              void tcmpoolpop(TCMPOOL *mpool, bool exe);
                     `mpool' specifies the memory pool object.
                     `exe' specifies whether to execute the destructor of the removed handler.

       The  function  `tcmpoolclear'  is  used in order to remove all cleanup handler of a memory
       pool object.

              void tcmpoolclear(TCMPOOL *mpool, bool exe);
                     `mpool' specifies the memory pool object.
                     `exe' specifies whether to execute the destructors of the removed handlers.

       The function `tcmpoolglobal' is used in order to get the global memory pool object.

              TCMPOOL *tcmpoolglobal(void);
                     The return value is the global memory pool object.
                     The global memory pool object is a singleton and assured to be deleted  when
                     the process is terminating normally.

API OF MISCELLANEOUS UTILITIES

       The function `tclmax' is used in order to get the larger value of two integers.

              long tclmax(long a, long b);
                     `a' specifies an integer.
                     `b' specifies the other integer.
                     The return value is the larger value of the two.

       The function `tclmin' is used in order to get the lesser value of two integers.

              long tclmin(long a, long b);
                     `a' specifies an integer.
                     `b' specifies the other integer.
                     The return value is the lesser value of the two.

       The  function  `tclrand'  is used in order to get a random number as long integer based on
       uniform distribution.

              unsigned long tclrand(void);
                     The return value is the random number between 0 and `ULONG_MAX'.
                     This function uses the random number source  device  and  generates  a  real
                     random number if possible.

       The  function `tcdrand' is used in order to get a random number as double decimal based on
       uniform distribution.

              double tcdrand(void);
                     The return value is the random number equal to or greater than 0,  and  less
                     than 1.0.
                     This  function  uses  the  random  number source device and generates a real
                     random number if possible.

       The function `tcdrandnd' is used in order to get a random number as double  decimal  based
       on normal distribution.

              double tcdrandnd(double avg, double sd);
                     `avg' specifies the average.
                     `sd' specifies the standard deviation.
                     The return value is the random number.
                     This  function  uses  the  random  number source device and generates a real
                     random number if possible.

       The function `tcstricmp' is used in order to compare two  strings  with  case  insensitive
       evaluation.

              int tcstricmp(const char *astr, const char *bstr);
                     `astr' specifies a string.
                     `bstr' specifies of the other string.
                     The return value is positive if the former is big, negative if the latter is
                     big, 0 if both are equivalent.

       The function `tcstrfwm' is used in order to check whether a string begins with a key.

              bool tcstrfwm(const char *str, const char *key);
                     `str' specifies the target string.
                     `key' specifies the forward matching key string.
                     The return value is true if the target string begins with the key, else,  it
                     is false.

       The function `tcstrifwm' is used in order to check whether a string begins with a key with
       case insensitive evaluation.

              bool tcstrifwm(const char *str, const char *key);
                     `str' specifies the target string.
                     `key' specifies the forward matching key string.
                     The return value is true if the target string begins with the key, else,  it
                     is false.

       The function `tcstrbwm' is used in order to check whether a string ends with a key.

              bool tcstrbwm(const char *str, const char *key);
                     `str' specifies the target string.
                     `key' specifies the backward matching key string.
                     The return value is true if the target string ends with the key, else, it is
                     false.

       The function `tcstribwm' is used in order to check whether a string ends with a  key  with
       case insensitive evaluation.

              bool tcstribwm(const char *str, const char *key);
                     `str' specifies the target string.
                     `key' specifies the backward matching key string.
                     The return value is true if the target string ends with the key, else, it is
                     false.

       The function `tcstrdist' is used in order to calculate the edit distance of two strings.

              int tcstrdist(const char *astr, const char *bstr);
                     `astr' specifies a string.
                     `bstr' specifies of the other string.
                     The return value is the edit distance which  is  known  as  the  Levenshtein
                     distance.  The cost is calculated by byte.

       The  function  `tcstrdistutf' is used in order to calculate the edit distance of two UTF-8
       strings.

              int tcstrdistutf(const char *astr, const char *bstr);
                     `astr' specifies a string.
                     `bstr' specifies of the other string.
                     The return value is the edit distance which  is  known  as  the  Levenshtein
                     distance.  The cost is calculated by Unicode character.

       The function `tcstrtoupper' is used in order to convert the letters of a string into upper
       case.

              char *tcstrtoupper(char *str);
                     `str' specifies the string to be converted.
                     The return value is the string itself.

       The function `tcstrtolower' is used in order to convert the letters of a string into lower
       case.

              char *tcstrtolower(char *str);
                     `str' specifies the string to be converted.
                     The return value is the string itself.

       The  function  `tcstrtrim'  is  used in order to cut space characters at head or tail of a
       string.

              char *tcstrtrim(char *str);
                     `str' specifies the string to be converted.
                     The return value is the string itself.

       The function `tcstrsqzspc' is used in order to squeeze space characters in  a  string  and
       trim it.

              char *tcstrsqzspc(char *str);
                     `str' specifies the string to be converted.
                     The return value is the string itself.

       The function `tcstrsubchr' is used in order to substitute characters in a string.

              char *tcstrsubchr(char *str, const char *rstr, const char *sstr);
                     `str' specifies the string to be converted.
                     `rstr' specifies the string containing characters to be replaced.
                     `sstr' specifies the string containing characters to be substituted.
                     If   the   substitute   string  is  shorter  then  the  replacement  string,
                     corresponding characters are removed.

       The function `tcstrcntutf' is used in order to count the number of characters in a  string
       of UTF-8.

              int tcstrcntutf(const char *str);
                     `str' specifies the string of UTF-8.
                     The return value is the number of characters in the string.

       The  function  `tcstrcututf'  is  used  in order to cut a string of UTF-8 at the specified
       number of characters.

              char *tcstrcututf(char *str, int num);
                     `str' specifies the string of UTF-8.
                     `num' specifies the number of characters to be kept.
                     The return value is the string itself.

       The function `tcstrutftoucs' is used in order to convert  a  UTF-8  string  into  a  UCS-2
       array.

              void tcstrutftoucs(const char *str, uint16_t *ary, int *np);
                     `str' specifies the UTF-8 string.
                     `ary'  specifies the pointer to the region into which the result UCS-2 codes
                     are written.  The size of the buffer should be sufficient.
                     `np' specifies the pointer to a variable into which the number  of  elements
                     of the result array is assigned.

       The  function  `tcstrucstoutf'  is  used  in  order  to convert a UCS-2 array into a UTF-8
       string.

              int tcstrucstoutf(const uint16_t *ary, int num, char *str);
                     `ary' specifies the array of UCS-2 codes.
                     `num' specifies the number of the array.
                     `str' specifies the pointer to the region into which the result UTF-8 string
                     is written.  The size of the buffer should be sufficient.
                     The return value is the length of the result string.

       The function `tcstrsplit' is used in order to create a list object by splitting a string.

              TCLIST *tcstrsplit(const char *str, const char *delims);
                     `str' specifies the source string.
                     `delims' specifies a string containing delimiting characters.
                     The return value is a list object of the split elements.
                     If  two  delimiters  are  successive, it is assumed that an empty element is
                     between the two.  Because the object of the return value is created with the
                     function  `tclistnew',  it  should  be deleted with the function `tclistdel'
                     when it is no longer in use.

       The function `tcstrjoin' is used in order to create a string by joining all elements of  a
       list object.

              char *tcstrjoin(const TCLIST *list, char delim);
                     `list' specifies a list object.
                     `delim' specifies a delimiting character.
                     The return value is the result string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcatoi' is used in order to convert a string to an integer.

              int64_t tcatoi(const char *str);
                     `str' specifies the string.
                     The return value is the integer.  If the string  does  not  contain  numeric
                     expression, 0 is returned.
                     This function is equivalent to `atoll' except that it does not depend on the
                     locale.

       The function `tcatoix' is used in order to convert a string with a  metric  prefix  to  an
       integer.

              int64_t tcatoix(const char *str);
                     `str'  specifies the string, which can be trailed by a binary metric prefix.
                     "K", "M", "G", "T", "P", and "E" are supported.  They are case-insensitive.
                     The return value is the integer.  If the string  does  not  contain  numeric
                     expression, 0 is returned.  If the integer overflows the domain, `INT64_MAX'
                     or `INT64_MIN' is returned according to the sign.

       The function `tcatof' is used in order to convert a string to a real number.

              double tcatof(const char *str);
                     `str' specifies the string.
                     The return value is the real number.  If the string does not contain numeric
                     expression, 0.0 is returned.
                     This  function is equivalent to `atof' except that it does not depend on the
                     locale.

       The function `tcregexmatch' is used in order to check whether a string matches  a  regular
       expression.

              bool tcregexmatch(const char *str, const char *regex);
                     `str' specifies the target string.
                     `regex' specifies the regular expression string.  If it begins with `*', the
                     trailing substring is used as a case-insensitive regular expression.
                     The return value is true if matching is success, else, it is false.

       The function `tcregexreplace' is used in  order  to  replace  each  substring  matching  a
       regular expression string.

              char *tcregexreplace(const char *str, const char *regex, const char *alt);
                     `str' specifies the target string.
                     `regex'  specifies  the  regular  expression  string  for substrings.  If it
                     begins with `*', the  trailing  substring  is  used  as  a  case-insensitive
                     regular expression.
                     `alt'  specifies  the  alternative  string  with  which  each  substrings is
                     replaced.  Each `&' in the string is replaced with  the  matched  substring.
                     Each  `ยด in the string escapes the following character.  Special escapes "1"
                     through "9" referring to the corresponding matching sub-expressions  in  the
                     regular expression string are supported.
                     The  return value is a new converted string.  Even if the regular expression
                     is invalid, a copy of the original string is returned.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcmd5hash' is used in order to get the MD5 hash value of a serial object.

              void tcmd5hash(const void *ptr, int size, char *buf);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `buf'  specifies  the  pointer to the region into which the result string is
                     written.  The size of the buffer should be equal to or more than 48 bytes.

       The function `tcarccipher' is used in order to cipher or decipher a serial object with the
       Arcfour stream cipher.

              void  tcarccipher(const  void  *ptr,  int  size,  const  void *kbuf, int ksiz, void
              *obuf);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `kbuf' specifies the pointer to the region of the cipher key.
                     `ksiz' specifies the size of the region of the cipher key.
                     `obuf' specifies the pointer to the region into which  the  result  data  is
                     written.   The  size of the buffer should be equal to or more than the input
                     region.

       The function `tctime' is used in order to get the time of day in seconds.

              double tctime(void);
                     The return value is the  time  of  day  in  seconds.   The  accuracy  is  in
                     microseconds.

       The function `tccalendar' is used in order to get the Gregorian calendar of a time.

              void  tccalendar(int64_t  t,  int jl, int *yearp, int *monp, int *dayp, int *hourp,
              int *minp, int *secp);
                     `t' specifies the  source  time  in  seconds  from  the  epoch.   If  it  is
                     `INT64_MAX', the current time is specified.
                     `jl'  specifies  the  jet lag of a location in seconds.  If it is `INT_MAX',
                     the local jet lag is specified.
                     `yearp' specifies the pointer to a variable to which the year  is  assigned.
                     If it is `NULL', it is not used.
                     `monp'  specifies  the pointer to a variable to which the month is assigned.
                     If it is `NULL', it is not used.  1 means January and 12 means December.
                     `dayp' specifies the pointer to a variable to which the day of the month  is
                     assigned.  If it is `NULL', it is not used.
                     `hourp'  specifies the pointer to a variable to which the hours is assigned.
                     If it is `NULL', it is not used.
                     `minp' specifies the pointer to a variable to which the minutes is assigned.
                     If it is `NULL', it is not used.
                     `secp' specifies the pointer to a variable to which the seconds is assigned.
                     If it is `NULL', it is not used.

       The function `tcdatestrwww' is used in order to format a date as a string in W3CDTF.

              void tcdatestrwww(int64_t t, int jl, char *buf);
                     `t' specifies the  source  time  in  seconds  from  the  epoch.   If  it  is
                     `INT64_MAX', the current time is specified.
                     `jl'  specifies  the  jet lag of a location in seconds.  If it is `INT_MAX',
                     the local jet lag is specified.
                     `buf' specifies the pointer to the region into which the  result  string  is
                     written.  The size of the buffer should be equal to or more than 48 bytes.
                     W3CDTF represents a date as "YYYY-MM-DDThh:mm:ddTZD".

       The  function  `tcdatestrhttp'  is  used in order to format a date as a string in RFC 1123
       format.

              void tcdatestrhttp(int64_t t, int jl, char *buf);
                     `t' specifies the  source  time  in  seconds  from  the  epoch.   If  it  is
                     `INT64_MAX', the current time is specified.
                     `jl'  specifies  the  jet lag of a location in seconds.  If it is `INT_MAX',
                     the local jet lag is specified.
                     `buf' specifies the pointer to the region into which the  result  string  is
                     written.  The size of the buffer should be equal to or more than 48 bytes.
                     RFC 1123 format represents a date as "Wdy, DD-Mon-YYYY hh:mm:dd TZD".

       The function `tcstrmktime' is used in order to get the time value of a date string.

              int64_t tcstrmktime(const char *str);
                     `str'  specifies the date string in decimal, hexadecimal, W3CDTF, or RFC 822
                     (1123).  Decimal can be trailed by "s" for in seconds, "m" for  in  minutes,
                     "h" for in hours, and "d" for in days.
                     The  return value is the time value of the date or `INT64_MIN' if the format
                     is invalid.

       The function `tcjetlag' is used in order to get the jet lag of the local time.

              int tcjetlag(void);
                     The return value is the jet lag of the local time in seconds.

       The function `tcdayofweek' is used in order to get the day of week of a date.

              int tcdayofweek(int year, int mon, int day);
                     `year' specifies the year of a date.
                     `mon' specifies the month of the date.
                     `day' specifies the day of the date.
                     The return value is the day of week of the date.  0 means Sunday and 6 means
                     Saturday.

API OF FILESYSTEM UTILITIES

       The  function  `tcrealpath'  is  used in order to get the canonicalized absolute path of a
       file.

              char *tcrealpath(const char *path);
                     `path' specifies the path of the file.
                     The return value is the canonicalized absolute path of a file, or `NULL'  if
                     the path is invalid.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcstatfile' is used in order to get the status information of a file.

              bool tcstatfile(const char *path, bool *isdirp, int64_t *sizep, int64_t *mtimep);
                     `path' specifies the path of the file.
                     `isdirp' specifies the pointer to a variable into which whether the file  is
                     a directory is assigned.  If it is `NULL', it is ignored.
                     `sizep'  specifies the pointer to a variable into which the size of the file
                     is assigned.  If it is `NULL', it is ignored.
                     `ntimep' specifies the pointer to a variable into which the size of the file
                     is assigned.  If it is `NULL', it is ignored.
                     If successful, the return value is true, else, it is false.

       The function `tcreadfile' is used in order to read whole data of a file.

              void *tcreadfile(const char *path, int limit, int *sp);
                     `path'  specifies the path of the file.  If it is `NULL', the standard input
                     is specified.
                     `limit' specifies the limiting size of reading data.  If it is not more than
                     0, the limitation is not specified.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.  If it is `NULL', it is not used.
                     The return value is the pointer to the allocated region of the read data, or
                     `NULL' if the file could not be opened.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when when is no longer in use.

       The function `tcreadfilelines' is used in order to read every line of a file.

              TCLIST *tcreadfilelines(const char *path);
                     `path' specifies the path of the file.  If it is `NULL', the standard  input
                     is specified.
                     The  return  value is a list object of every lines if successful, else it is
                     `NULL'.
                     Line separators are cut out.  Because the object  of  the  return  value  is
                     created  with  the  function  `tclistnew',  it  should  be  deleted with the
                     function `tclistdel' when it is no longer in use.

       The function `tcwritefile' is used in order to write data into a file.

              bool tcwritefile(const char *path, const void *ptr, int size);
                     `path' specifies the path of the file.  If it is `NULL', the standard output
                     is specified.
                     `ptr' specifies the pointer to the data region.
                     `size' specifies the size of the region.
                     If successful, the return value is true, else, it is false.

       The function `tccopyfile' is used in order to copy a file.

              bool tccopyfile(const char *src, const char *dest);
                     `src' specifies the path of the source file.
                     `dest' specifies the path of the destination file.
                     The return value is true if successful, else, it is false.
                     If the destination file exists, it is overwritten.

       The function `tcreaddir' is used in order to read names of files in a directory.

              TCLIST *tcreaddir(const char *path);
                     `path' specifies the path of the directory.
                     The return value is a list object of names if successful, else it is `NULL'.
                     Links to the directory itself and to the parent directory are ignored.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tclistnew', it should be deleted with the function `tclistdel' when  it  is
                     no longer in use.

       The  function  `tcglobpat'  is  used  in  order to expand a pattern into a list of matched
       paths.

              TCLIST *tcglobpat(const char *pattern);
                     `pattern' specifies the matching pattern.
                     The return value is a list object of matched paths.  If no path is  matched,
                     an empty list is returned.
                     Because  the  object  of  the  return  value  is  created  with the function
                     `tclistnew', it should be deleted with the function `tclistdel' when  it  is
                     no longer in use.

       The  function  `tcremovelink' is used in order to remove a file or a directory and its sub
       ones recursively.

              bool tcremovelink(const char *path);
                     `path' specifies the path of the link.
                     If successful, the return value is  true,  else,  it  is  false.   False  is
                     returned when the link does not exist or the permission is denied.

       The function `tcwrite' is used in order to write data into a file.

              bool tcwrite(int fd, const void *buf, size_t size);
                     `fd' specifies the file descriptor.
                     `buf' specifies the buffer to be written.
                     `size' specifies the size of the buffer.
                     The return value is true if successful, else, it is false.

       The function `tcread' is used in order to read data from a file.

              bool tcread(int fd, void *buf, size_t size);
                     `fd' specifies the file descriptor.
                     `buf' specifies the buffer to store into.
                     `size' specifies the size of the buffer.
                     The return value is true if successful, else, it is false.

       The function `tclock' is used in order to lock a file.

              bool tclock(int fd, bool ex, bool nb);
                     `fd' specifies the file descriptor.
                     `ex' specifies whether an exclusive lock or a shared lock is performed.
                     `nb' specifies whether to request with non-blocking.
                     The return value is true if successful, else, it is false.

       The function `tcunlock' is used in order to unlock a file.

              bool tcunlock(int fd);
                     `fd' specifies the file descriptor.
                     The return value is true if successful, else, it is false.

       The function `tcsystem' is used in order to execute a shell command.

              int tcsystem(const char **args, int anum);
                     `args' specifies an array of the command name and its arguments.
                     `anum' specifies the number of elements of the array.
                     The return value is the exit code of the command or `INT_MAX' on failure.
                     The  command  name  and  the  arguments  are  quoted and meta characters are
                     escaped.

API OF ENCODING UTILITIES

       The function `tcurlencode' is used in order to encode a serial object with URL encoding.

              char *tcurlencode(const char *ptr, int size);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     The return value is the result string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call if when is no longer in use.

       The function `tcurldecode' is used in order to decode a string encoded with URL encoding.

              char *tcurldecode(const char *str, int *sp);
                     `str' specifies the encoded string.
                     `sp'  specifies  the pointer to a variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the result.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcurlbreak' is used in order to break up a URL into elements.

              TCMAP *tcurlbreak(const char *str);
                     `str' specifies the URL string.
                     The return value is the map object whose keys are the name of elements.  The
                     key "self" indicates the URL itself.  The key "scheme" indicates the scheme.
                     The  key  "host" indicates the host of the server.  The key "port" indicates
                     the port number of the server.  The key "authority" indicates the  authority
                     information.   The  key  "path" indicates the path of the resource.  The key
                     "file" indicates the file name  without  the  directory  section.   The  key
                     "query"  indicates  the  query  string.   The  key  "fragment" indicates the
                     fragment string.
                     Supported schema are HTTP, HTTPS, FTP, and FILE.  Absolute URL and  relative
                     URL  are  supported.  Because the object of the return value is created with
                     the function `tcmapnew', it should be deleted with the  function  `tcmapdel'
                     when it is no longer in use.

       The  function  `tcurlresolve'  is used in order to resolve a relative URL with an absolute
       URL.

              char *tcurlresolve(const char *base, const char *target);
                     `base' specifies the absolute URL of the base location.
                     `target' specifies the URL to be resolved.
                     The return value is the resolved URL.  If the target URL is relative, a  new
                     URL  of  relative location from the base location is returned.  Else, a copy
                     of the target URL is returned.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The  function  `tcbaseencode'  is  used  in  order  to  encode a serial object with Base64
       encoding.

              char *tcbaseencode(const char *ptr, int size);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     The return value is the result string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call if when is no longer in use.

       The  function  `tcbasedecode'  is  used  in  order  to decode a string encoded with Base64
       encoding.

              char *tcbasedecode(const char *str, int *sp);
                     `str' specifies the encoded string.
                     `sp' specifies the pointer to a variable into which the size of  the  region
                     of the return value is assigned.
                     The return value is the pointer to the region of the result.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The  function  `tcquoteencode'  is  used  in  order  to  encode  a  serial   object   with
       Quoted-printable encoding.

              char *tcquoteencode(const char *ptr, int size);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     The return value is the result string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call if when is no longer in use.

       The  function  `tcquotedecode'  is  used  in  order  to  decode  a  string  encoded   with
       Quoted-printable encoding.

              char *tcquotedecode(const char *str, int *sp);
                     `str' specifies the encoded string.
                     `sp'  specifies  the pointer to a variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the result.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcmimeencode' is used in order to encode a string with MIME encoding.

              char *tcmimeencode(const char *str, const char *encname, bool base);
                     `str' specifies the string.
                     `encname' specifies the string of the name of the character encoding.
                     `base'   specifies  whether  to  use  Base64  encoding.   If  it  is  false,
                     Quoted-printable is used.
                     The return value is the result string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The  function  `tcmimedecode'  is  used  in  order  to  decode  a string encoded with MIME
       encoding.

              char *tcmimedecode(const char *str, char *enp);
                     `str' specifies the encoded string.
                     `enp' specifies the pointer to the region into which the name of encoding is
                     written.  If it is `NULL', it is not used.  The size of the buffer should be
                     equal to or more than 32 bytes.
                     The return value is the result string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcmimebreak' is used in order to split a string of MIME into headers and the
       body.

              char *tcmimebreak(const char *ptr, int size, TCMAP *headers, int *sp);
                     `ptr' specifies the pointer to the region of MIME data.
                     `size' specifies the size of the region.
                     `headers' specifies a map object to store headers.  If it is `NULL',  it  is
                     not used.  Each key of the map is an uncapitalized header name.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the body data.
                     If the content type is defined, the header map has the key "TYPE" specifying
                     the type.  If the character encoding is defined, the key "CHARSET" indicates
                     the encoding name.  If the boundary string of multipart is defined, the  key
                     "BOUNDARY" indicates the string.  If the content disposition is defined, the
                     key "DISPOSITION" indicates the direction.  If the file name is defined, the
                     key  "FILENAME"  indicates  the name.  If the attribute name is defined, the
                     key "NAME" indicates the name.  Because the region of the  return  value  is
                     allocated with the `malloc' call, it should be released with the `free' call
                     when it is no longer in use.

       The function `tcmimeparts' is used in order to split  multipart  data  of  MIME  into  its
       parts.

              TCLIST *tcmimeparts(const char *ptr, int size, const char *boundary);
                     `ptr' specifies the pointer to the region of multipart data of MIME.
                     `size' specifies the size of the region.
                     `boundary' specifies the boundary string.
                     The  return value is a list object.  Each element of the list is the data of
                     a part.
                     Because the object  of  the  return  value  is  created  with  the  function
                     `tclistnew',  it  should be deleted with the function `tclistdel' when it is
                     no longer in use.

       The function `tchexencode' is used in order to encode a  serial  object  with  hexadecimal
       encoding.

              char *tchexencode(const char *ptr, int size);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     The return value is the result string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call if when is no longer in use.

       The function `tchexdecode' is used in order to decode a string  encoded  with  hexadecimal
       encoding.

              char *tchexdecode(const char *str, int *sp);
                     `str' specifies the encoded string.
                     `sp'  specifies  the pointer to a variable into which the size of the region
                     of the return
                     value is assigned.
                     The return value is the pointer to the region of the result.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The  function  `tcpackencode'  is  used in order to compress a serial object with Packbits
       encoding.

              char *tcpackencode(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If  successful,  the return value is the pointer to the result object, else,
                     it is `NULL'.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcpackdecode' is used in order to decompress a serial object compressed with
       Packbits encoding.

              char *tcpackdecode(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp' specifies the pointer to a variable into which the size of  the  region
                     of the return value is assigned.
                     If  successful,  the return value is the pointer to the result object, else,
                     it is `NULL'.
                     Because an additional zero code is appended at the end of the region of  the
                     return  value,  the  return  value  can  be  treated  as a character string.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcbsencode' is used in order to compress a serial object with TCBS encoding.

              char *tcbsencode(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the result  object,  else,
                     it is `NULL'.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcbsdecode' is used in order to decompress a serial object  compressed  with
       TCBS encoding.

              char *tcbsdecode(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp'  specifies  the pointer to a variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the result  object,  else,
                     it is `NULL'.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcdeflate' is used in  order  to  compress  a  serial  object  with  Deflate
       encoding.

              char *tcdeflate(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the result  object,  else,
                     it is `NULL'.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcinflate' is used in order to decompress a serial  object  compressed  with
       Deflate encoding.

              char *tcinflate(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp'  specifies  the pointer to a variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the result  object,  else,
                     it is `NULL'.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcgzipencode' is used in  order  to  compress  a  serial  object  with  GZIP
       encoding.

              char *tcgzipencode(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the result  object,  else,
                     it is `NULL'.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcgzipdecode' is used in order to decompress a serial object compressed with
       GZIP encoding.

              char *tcgzipdecode(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp'  specifies  the pointer to a variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the result  object,  else,
                     it is `NULL'.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcgetcrc' is used in order to get the CRC32 checksum of a serial object.

              unsigned int tcgetcrc(const char *ptr, int size);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     The return value is the CRC32 checksum of the object.

       The function `tcbzipencode' is used in order  to  compress  a  serial  object  with  BZIP2
       encoding.

              char *tcbzipencode(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp' specifies the pointer to the variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the result  object,  else,
                     it is `NULL'.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcbzipdecode' is used in order to decompress a serial object compressed with
       BZIP2 encoding.

              char *tcbzipdecode(const char *ptr, int size, int *sp);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `sp'  specifies  the pointer to a variable into which the size of the region
                     of the return value is assigned.
                     If successful, the return value is the pointer to the result  object,  else,
                     it is `NULL'.
                     Because  an additional zero code is appended at the end of the region of the
                     return value, the return  value  can  be  treated  as  a  character  string.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call when it is no longer in use.

       The function `tcberencode' is used in order to encode an  array  of  nonnegative  integers
       with BER encoding.

              char *tcberencode(const unsigned int *ary, int anum, int *sp);
                     `ary' specifies the pointer to the array of nonnegative integers.
                     `anum' specifies the size of the array.
                     `sp'  specifies  the pointer to a variable into which the size of the region
                     of the return value is assigned.
                     The return value is the pointer to the region of the result.
                     Because the region of the return value is allocated with the `malloc'  call,
                     it should be released with the `free' call if when is no longer in use.

       The  function  `tcberdecode'  is  used in order to decode a serial object encoded with BER
       encoding.

              unsigned int *tcberdecode(const char *ptr, int size, int *np);
                     `ptr' specifies the pointer to the region.
                     `size' specifies the size of the region.
                     `np' specifies the pointer to a variable into which the number  of  elements
                     of the return value is assigned.
                     The return value is the pointer to the array of the result.
                     Because  the region of the return value is allocated with the `malloc' call,
                     it should be released with the `free' call if when is no longer in use.

       The function `tcxmlescape' is used in order to escape meta characters in a string with the
       entity references of XML.

              char *tcxmlescape(const char *str);
                     `str' specifies the string.
                     The return value is the pointer to the escaped string.
                     This  function  escapes  only `&', `<', `>', and `"'.  Because the region of
                     the return value is allocated with the `malloc' call, it should be  released
                     with the `free' call when it is no longer in use.

       The function `tcxmlunescape' is used in order to unescape entity references in a string of
       XML.

              char *tcxmlunescape(const char *str);
                     `str' specifies the string.
                     The return value is the unescaped string.
                     This function restores only `&amp;', `&lt;', `&gt;', and `&quot;'.   Because
                     the  region  of  the  return  value  is allocated with the `malloc' call, it
                     should be released with the `free' call when it is no longer in use.

SEE ALSO

       tcutest(1), tcucodec(1), tokyocabinet(3)