TCUTIL(3) Tokyo Cabinet TCUTIL(3)NAME
tcutil - the utility API
DESCRIPTION
The utility API is a set of routines to handle records on memory eas‐
ily. 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 `tcmap‐
new' 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 informa‐
tion.
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 mem‐
ory.
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 nulli‐
fied 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 mem‐
ory.
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 mem‐
ory.
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 con‐
taining 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 out‐
put 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 char‐
acters 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' con‐
verts 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 char‐
acters 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' con‐
verts 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 ele‐
ment 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 ele‐
ments, 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 ele‐
ment.
`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 ele‐
ment.
`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 ele‐
ment.
`size' specifies the size of the region.
If `index' is equal to or more than the number of ele‐
ments, 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 ele‐
ments, 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 ele‐
ment 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 over‐
written.
`ptr' specifies the pointer to the region of the new con‐
tent.
`size' specifies the size of the new content.
If `index' is equal to or more than the number of ele‐
ments, this function has no effect.
The function `tclistover2' is used in order to overwrite a string ele‐
ment 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 over‐
written.
`str' specifies the string of the new content.
If `index' is equal to or more than the number of ele‐
ments, 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 cre‐
ated.
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 cre‐
ated.
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 itera‐
tor 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 mem‐
ory 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 con‐
taining 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 con‐
taining 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 corre‐
sponds, 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 param‐
eter 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 for‐
mer 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'
(dafault), `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 cre‐
ated.
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 cre‐
ated.
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 itera‐
tor 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 con‐
taining 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 con‐
taining 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 corre‐
sponds, 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 cre‐
ated.
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 cre‐
ated.
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 itera‐
tor 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 mem‐
ory 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 corre‐
sponds, 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'
(dafault), `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 cre‐
ated.
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 cre‐
ated.
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 itera‐
tor 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 mem‐
ory 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 corre‐
sponds, 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 rele‐
gated. 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 rele‐
gated. 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 extensi‐
ble 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 rel‐
egated 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 han‐
dler 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 dou‐
ble 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, nega‐
tive 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 dis‐
tance 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 dis‐
tance 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 Uni‐
code 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 charac‐
ters.
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 `tclist‐
new', 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 inte‐
ger.
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 met‐
ric 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 inte‐
ger 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 sub‐
string 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 sub‐
strings. 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 sup‐
ported.
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 sec‐
onds.
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 calen‐
dar 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 sec‐
onds.
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 informa‐
tion 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 suc‐
cessful, 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 ele‐
ments.
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 sec‐
tion. The key "query" indicates the query string. The
key "fragment" indicates the fragment string.
Supported schema are HTTP, HTTPS, FTP, and FILE. Abso‐
lute 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 charac‐
ter 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 encod‐
ing 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 non‐
negative 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 refer‐
ences 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 `&', `<', `>', 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.
SEE ALSOtcutest(1), tcucodec(1), tokyocabinet(3)Man Page 2012-08-18 TCUTIL(3)
