tcutil.3

Tokyo Cabinet的Tokyo Cabinet 是一个DBM的实现。这里的数据库由一系列key-value对的记录构成。key和value都可以是任意长度的字节序列,既可以是二进制也可以是字符

.TH "TCUTIL" 3 "2009-02-13" "Man Page" "Tokyo Cabinet"

.SH NAME
tcutil \- the utility API

.SH DESCRIPTION
.PP
The utility API is a set of routines to handle records on memory easily.  Especially, extensible string, array list, hash map, and ordered tree are useful.
.PP
To use the utility API, include `\fBtcutil.h\fR' and related standard header files.  Usually, write the following description near the front of a source file.
.PP
.RS
.br
\fB#include <tcutil.h>\fR
.br
\fB#include <stdlib.h>\fR
.br
\fB#include <time.h>\fR
.br
\fB#include <stdbool.h>\fR
.br
\fB#include <stdint.h>\fR
.RE
.PP
Objects whose type is pointer to `\fBTCXSTR\fR' are used for extensible string.  An extensible string object is created with the function `\fBtcxstrnew\fR' and is deleted with the function `\fBtcxstrdel\fR'.  Objects whose type is pointer to `\fBTCLIST\fR' are used for array list.  A list object is created with the function `\fBtclistnew\fR' and is deleted with the function `\fBtclistdel\fR'.  Objects whose type is pointer to `\fBTCMAP\fR' are used for hash map.  A map object is created with the function `\fBtcmapnew\fR' and is deleted with the function `\fBtcmapdel\fR'.  Objects whose type is pointer to `\fBTCTREE\fR' are used for ordered tree.  A tree object is created with the function `\fBtctreenew\fR' and is deleted with the function `\fBtctreedel\fR'.  To avoid memory leak, it is important to delete every object when it is no longer in use.

.SH API OF BASIC UTILITIES
.PP
The constant `tcversion' is the string containing the version information.
.PP
.RS
.br
\fBextern const char *tcversion;\fR
.RE
.PP
The variable `tcfatalfunc' is the pointer to the call back function for handling a fatal error.
.PP
.RS
.br
\fBextern void (*tcfatalfunc)(const char *);\fR
.RS
The argument specifies the error message.
.RE
.RS
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.
.RE
.RE
.PP
The function `tcmalloc' is used in order to allocate a region on memory.
.PP
.RS
.br
\fBvoid *tcmalloc(size_t \fIsize\fB);\fR
.RS
`\fIsize\fR' specifies the size of the region.
.RE
.RS
The return value is the pointer to the allocated region.
.RE
.RS
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.
.RE
.RE
.PP
The function `tccalloc' is used in order to allocate a nullified region on memory.
.PP
.RS
.br
\fBvoid *tccalloc(size_t \fInmemb\fB, size_t \fIsize\fB);\fR
.RS
`\fInmemb\fR' specifies the number of elements.
.RE
.RS
`\fIsize\fR' specifies the size of each element.
.RE
.RS
The return value is the pointer to the allocated nullified region.
.RE
.RS
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.
.RE
.RE
.PP
The function `tcrealloc' is used in order to re\-allocate a region on memory.
.PP
.RS
.br
\fBvoid *tcrealloc(void *\fIptr\fB, size_t \fIsize\fB);\fR
.RS
`\fIptr\fR' specifies the pointer to the region.
.RE
.RS
`\fIsize\fR' specifies the size of the region.
.RE
.RS
The return value is the pointer to the re\-allocated region.
.RE
.RS
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.
.RE
.RE
.PP
The function `tcmemdup' is used in order to duplicate a region on memory.
.PP
.RS
.br
\fBvoid *tcmemdup(const void *\fIptr\fB, size_t \fIsize\fB);\fR
.RS
`\fIptr\fR' specifies the pointer to the region.
.RE
.RS
`\fIsize\fR' specifies the size of the region.
.RE
.RS
The return value is the pointer to the allocated region of the duplicate.
.RE
.RS
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.
.RE
.RE
.PP
The function `tcstrdup' is used in order to duplicate a string on memory.
.PP
.RS
.br
\fBchar *tcstrdup(const void *\fIstr\fB);\fR
.RS
`\fIstr\fR' specifies the string.
.RE
.RS
The return value is the allocated string equivalent to the specified string.
.RE
.RS
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.
.RE
.RE
.PP
The function `tcfree' is used in order to free a region on memory.
.PP
.RS
.br
\fBvoid tcfree(void *\fIptr\fB);\fR
.RS
`\fIptr\fR' specifies the pointer to the region.  If it is `NULL', this function has no effect.
.RE
.RS
Although this function is just a wrapper of `free' call, this is useful in applications using another package of the `malloc' series.
.RE
.RE

.SH API OF EXTENSIBLE STRING
.PP
The function `tcxstrnew' is used in order to create an extensible string object.
.PP
.RS
.br
\fBTCXSTR *tcxstrnew(void);\fR
.RS
The return value is the new extensible string object.
.RE
.RE
.PP
The function `tcxstrnew2' is used in order to create an extensible string object from a character string.
.PP
.RS
.br
\fBTCXSTR *tcxstrnew2(const char *\fIstr\fB);\fR
.RS
`\fIstr\fR' specifies the string of the initial content.
.RE
.RS
The return value is the new extensible string object containing the specified string.
.RE
.RE
.PP
The function `tcxstrnew3' is used in order to create an extensible string object with the initial allocation size.
.PP
.RS
.br
\fBTCXSTR *tcxstrnew3(int \fIasiz\fB);\fR
.RS
`\fIasiz\fR' specifies the initial allocation size.
.RE
.RS
The return value is the new extensible string object.
.RE
.RE
.PP
The function `tcxstrdup' is used in order to copy an extensible string object.
.PP
.RS
.br
\fBTCXSTR *tcxstrdup(const TCXSTR *\fIxstr\fB);\fR
.RS
`\fIxstr\fR' specifies the extensible string object.
.RE
.RS
The return value is the new extensible string object equivalent to the specified object.
.RE
.RE
.PP
The function `tcxstrdel' is used in order to delete an extensible string object.
.PP
.RS
.br
\fBvoid tcxstrdel(TCXSTR *\fIxstr\fB);\fR
.RS
`\fIxstr\fR' specifies the extensible string object.
.RE
.RS
Note that the deleted object and its derivatives can not be used anymore.
.RE
.RE
.PP
The function `tcxstrcat' is used in order to concatenate a region to the end of an extensible string object.
.PP
.RS
.br
\fBvoid tcxstrcat(TCXSTR *\fIxstr\fB, const void *\fIptr\fB, int \fIsize\fB);\fR
.RS
`\fIxstr\fR' specifies the extensible string object.
.RE
.RS
`\fIptr\fR' specifies the pointer to the region to be appended.
.RE
.RS
`\fIsize\fR' specifies the size of the region.
.RE
.RE
.PP
The function `tcxstrcat2' is used in order to concatenate a character string to the end of an extensible string object.
.PP
.RS
.br
\fBvoid tcxstrcat2(TCXSTR *\fIxstr\fB, const char *\fIstr\fB);\fR
.RS
`\fIxstr\fR' specifies the extensible string object.
.RE
.RS
`\fIstr\fR' specifies the string to be appended.
.RE
.RE
.PP
The function `tcxstrptr' is used in order to get the pointer of the region of an extensible string object.
.PP
.RS
.br
\fBconst void *tcxstrptr(const TCXSTR *\fIxstr\fB);\fR
.RS
`\fIxstr\fR' specifies the extensible string object.
.RE
.RS
The return value is the pointer of the region of the object.
.RE
.RS
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.
.RE
.RE
.PP
The function `tcxstrsize' is used in order to get the size of the region of an extensible string object.
.PP
.RS
.br
\fBint tcxstrsize(const TCXSTR *\fIxstr\fB);\fR
.RS
`\fIxstr\fR' specifies the extensible string object.
.RE
.RS
The return value is the size of the region of the object.
.RE
.RE
.PP
The function `tcxstrclear' is used in order to clear an extensible string object.
.PP
.RS
.br
\fBvoid tcxstrclear(TCXSTR *\fIxstr\fB);\fR
.RS
`\fIxstr\fR' specifies the extensible string object.
.RE
.RS
The internal buffer of the object is cleared and the size is set zero.
.RE
.RE
.PP
The function `tcxstrprintf' is used in order to perform formatted output into an extensible string object.
.PP
.RS
.br
\fBvoid tcxstrprintf(TCXSTR *\fIxstr\fB, const char *\fIformat\fB, ...);\fR
.RS
`\fIxstr\fR' specifies the extensible string object.
.RE
.RS
`\fIformat\fR' specifies the printf\-like format string.  The conversion character `%' can be used with such flag characters as `s', `d', `o', `u', `x', `X', `c', `e', `E', `f', `g', `G', `@', `?', `b', and `%'.  `@' works as with `s' but escapes meta characters of XML.  `?' works as with `s' but escapes meta characters of URL.  `b' converts an integer to the string as binary numbers.  The other conversion character work as with each original.
.RE
.RS
The other arguments are used according to the format string.
.RE
.RE
.PP
The function `tcsprintf' is used in order to allocate a formatted string on memory.
.PP
.RS
.br
\fBchar *tcsprintf(const char *\fIformat\fB, ...);\fR
.RS
`\fIformat\fR' specifies the printf\-like format string.  The conversion character `%' can be used with such flag characters as `s', `d', `o', `u', `x', `X', `c', `e', `E', `f', `g', `G', `@', `?', `b', and `%'.  `@' works as with `s' but escapes meta characters of XML.  `?' works as with `s' but escapes meta characters of URL.  `b' converts an integer to the string as binary numbers.  The other conversion character work as with each original.
.RE
.RS
The other arguments are used according to the format string.
.RE
.RS
The return value is the pointer to the region of the result string.
.RE
.RS
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.
.RE
.RE

.SH API OF ARRAY LIST
.PP
The function `tclistnew' is used in order to create a list object.
.PP
.RS
.br
\fBTCLIST *tclistnew(void);\fR
.RS
The return value is the new list object.
.RE
.RE
.PP
The function `tclistnew2' is used in order to create a list object with expecting the number of elements.
.PP
.RS
.br
\fBTCLIST *tclistnew2(int \fIanum\fB);\fR
.RS
`\fIanum\fR' specifies the number of elements expected to be stored in the list.
.RE
.RS
The return value is the new list object.
.RE
.RE
.PP
The function `tclistnew3' is used in order to create a list object with initial string elements.
.PP
.RS
.br
\fBTCLIST *tclistnew3(const char *\fIstr\fB, ...);\fR
.RS
`\fIstr\fR' specifies the string of the first element.
.RE
.RS
The other arguments are other elements.  They should be trailed by a `NULL' argument.
.RE
.RS
The return value is the new list object.
.RE
.RE
.PP
The function `tclistdup' is used in order to copy a list object.
.PP
.RS
.br
\fBTCLIST *tclistdup(const TCLIST *\fIlist\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
The return value is the new list object equivalent to the specified object.
.RE
.RE
.PP
The function `tclistdel' is used in order to delete a list object.
.PP
.RS
.br
\fBvoid tclistdel(TCLIST *\fIlist\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
Note that the deleted object and its derivatives can not be used anymore.
.RE
.RE
.PP
The function `tclistnum' is used in order to get the number of elements of a list object.
.PP
.RS
.br
\fBint tclistnum(const TCLIST *\fIlist\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
The return value is the number of elements of the list.
.RE
.RE
.PP
The function `tclistval' is used in order to get the pointer to the region of an element of a list object.
.PP
.RS
.br
\fBconst void *tclistval(const TCLIST *\fIlist\fB, int \fIindex\fB, int *\fIsp\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
`\fIindex\fR' specifies the index of the element.
.RE
.RS
`\fIsp\fR' specifies the pointer to the variable into which the size of the region of the return value is assigned.
.RE
.RS
The return value is the pointer to the region of the value.
.RE
.RS
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'.
.RE
.RE
.PP
The function `tclistval2' is used in order to get the string of an element of a list object.
.PP
.RS
.br
\fBconst char *tclistval2(const TCLIST *\fIlist\fB, int \fIindex\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
`\fIindex\fR' specifies the index of the element.
.RE
.RS
The return value is the string of the value.
.RE
.RS
If `index' is equal to or more than the number of elements, the return value is `NULL'.
.RE
.RE
.PP
The function `tclistpush' is used in order to add an element at the end of a list object.
.PP
.RS
.br
\fBvoid tclistpush(TCLIST *\fIlist\fB, const void *\fIptr\fB, int \fIsize\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
`\fIptr\fR' specifies the pointer to the region of the new element.
.RE
.RS
`\fIsize\fR' specifies the size of the region.
.RE
.RE
.PP
The function `tclistpush2' is used in order to add a string element at the end of a list object.
.PP
.RS
.br
\fBvoid tclistpush2(TCLIST *\fIlist\fB, const char *\fIstr\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS