tcutil.3

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

`\fIstr\fR' specifies the string of the new element.
.RE
.RE
.PP
The function `tclistpop' is used in order to remove an element of the end of a list object.
.PP
.RS
.br
\fBvoid *tclistpop(TCLIST *\fIlist\fB, int *\fIsp\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.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 removed element.
.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.  If the list is empty, the return value is `NULL'.
.RE
.RE
.PP
The function `tclistpop2' is used in order to remove a string element of the end of a list object.
.PP
.RS
.br
\fBchar *tclistpop2(TCLIST *\fIlist\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
The return value is the string of the removed element.
.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.  If the list is empty, the return value is `NULL'.
.RE
.RE
.PP
The function `tclistunshift' is used in order to add an element at the top of a list object.
.PP
.RS
.br
\fBvoid tclistunshift(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 `tclistunshift2' is used in order to add a string element at the top of a list object.
.PP
.RS
.br
\fBvoid tclistunshift2(TCLIST *\fIlist\fB, const char *\fIstr\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
`\fIstr\fR' specifies the string of the new element.
.RE
.RE
.PP
The function `tclistshift' is used in order to remove an element of the top of a list object.
.PP
.RS
.br
\fBvoid *tclistshift(TCLIST *\fIlist\fB, int *\fIsp\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.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 removed element.
.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.  If the list is empty, the return value is `NULL'.
.RE
.RE
.PP
The function `tclistshift2' is used in order to remove a string element of the top of a list object.
.PP
.RS
.br
\fBchar *tclistshift2(TCLIST *\fIlist\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
The return value is the string of the removed element.
.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.  If the list is empty, the return value is `NULL'.
.RE
.RE
.PP
The function `tclistinsert' is used in order to add an element at the specified location of a list object.
.PP
.RS
.br
\fBvoid tclistinsert(TCLIST *\fIlist\fB, int \fIindex\fB, const void *\fIptr\fB, int \fIsize\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
`\fIindex\fR' specifies the index of the new element.
.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
.RS
If `index' is equal to or more than the number of elements, this function has no effect.
.RE
.RE
.PP
The function `tclistinsert2' is used in order to add a string element at the specified location of a list object.
.PP
.RS
.br
\fBvoid tclistinsert2(TCLIST *\fIlist\fB, int \fIindex\fB, const char *\fIstr\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
`\fIindex\fR' specifies the index of the new element.
.RE
.RS
`\fIstr\fR' specifies the string of the new element.
.RE
.RS
If `index' is equal to or more than the number of elements, this function has no effect.
.RE
.RE
.PP
The function `tclistremove' is used in order to remove an element at the specified location of a list object.
.PP
.RS
.br
\fBvoid *tclistremove(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 to be removed.
.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 removed element.
.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.  If `index' is equal to or more than the number of elements, no element is removed and the return value is `NULL'.
.RE
.RE
.PP
The function `tclistremove2' is used in order to remove a string element at the specified location of a list object.
.PP
.RS
.br
\fBchar *tclistremove2(TCLIST *\fIlist\fB, int \fIindex\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
`\fIindex\fR' specifies the index of the element to be removed.
.RE
.RS
The return value is the string of the removed element.
.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.  If `index' is equal to or more than the number of elements, no element is removed and the return value is `NULL'.
.RE
.RE
.PP
The function `tclistover' is used in order to overwrite an element at the specified location of a list object.
.PP
.RS
.br
\fBvoid tclistover(TCLIST *\fIlist\fB, int \fIindex\fB, const void *\fIptr\fB, int \fIsize\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
`\fIindex\fR' specifies the index of the element to be overwritten.
.RE
.RS
`\fIptr\fR' specifies the pointer to the region of the new content.
.RE
.RS
`\fIsize\fR' specifies the size of the new content.
.RE
.RS
If `index' is equal to or more than the number of elements, this function has no effect.
.RE
.RE
.PP
The function `tclistover2' is used in order to overwrite a string element at the specified location of a list object.
.PP
.RS
.br
\fBvoid tclistover2(TCLIST *\fIlist\fB, int \fIindex\fB, const char *\fIstr\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
`\fIindex\fR' specifies the index of the element to be overwritten.
.RE
.RS
`\fIstr\fR' specifies the string of the new content.
.RE
.RS
If `index' is equal to or more than the number of elements, this function has no effect.
.RE
.RE
.PP
The function `tclistsort' is used in order to sort elements of a list object in lexical order.
.PP
.RS
.br
\fBvoid tclistsort(TCLIST *\fIlist\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RE
.PP
The function `tclistlsearch' is used in order to search a list object for an element using liner search.
.PP
.RS
.br
\fBint tclistlsearch(const 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 key.
.RE
.RS
`\fIsize\fR' specifies the size of the region.
.RE
.RS
The return value is the index of a corresponding element or \-1 if there is no corresponding element.
.RE
.RS
If two or more elements correspond, the former returns.
.RE
.RE
.PP
The function `tclistbsearch' is used in order to search a list object for an element using binary search.
.PP
.RS
.br
\fBint tclistbsearch(const TCLIST *\fIlist\fB, const void *\fIptr\fB, int \fIsize\fB);\fR
.RS
`\fIlist\fR' specifies the list object.  It should be sorted in lexical order.
.RE
.RS
`\fIptr\fR' specifies the pointer to the region of the key.
.RE
.RS
`\fIsize\fR' specifies the size of the region.
.RE
.RS
The return value is the index of a corresponding element or \-1 if there is no corresponding element.
.RE
.RS
If two or more elements correspond, which returns is not defined.
.RE
.RE
.PP
The function `tclistclear' is used in order to clear a list object.
.PP
.RS
.br
\fBvoid tclistclear(TCLIST *\fIlist\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.RE
.RS
All elements are removed.
.RE
.RE
.PP
The function `tclistdump' is used in order to serialize a list object into a byte array.
.PP
.RS
.br
\fBvoid *tclistdump(const TCLIST *\fIlist\fB, int *\fIsp\fB);\fR
.RS
`\fIlist\fR' specifies the list object.
.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 result serial region.
.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 `tclistload' is used in order to create a list object from a serialized byte array.
.PP
.RS
.br
\fBTCLIST *tclistload(const void *\fIptr\fB, int \fIsize\fB);\fR
.RS
`\fIptr\fR' specifies the pointer to the region of serialized byte array.
.RE
.RS
`\fIsize\fR' specifies the size of the region.
.RE
.RS
The return value is a new list object.
.RE
.RS
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.
.RE
.RE

.SH API OF HASH MAP
.PP
The function `tcmapnew' is used in order to create a map object.
.PP
.RS
.br
\fBTCMAP *tcmapnew(void);\fR
.RS
The return value is the new map object.
.RE
.RE
.PP
The function `tcmapnew2' is used in order to create a map object with specifying the number of the buckets.
.PP
.RS
.br
\fBTCMAP *tcmapnew2(uint32_t \fIbnum\fB);\fR
.RS
`\fIbnum\fR' specifies the number of the buckets.
.RE
.RS
The return value is the new map object.
.RE
.RE
.PP
The function `tcmapnew3' is used in order to create a map object with initial string elements.
.PP
.RS
.br
\fBTCMAP *tcmapnew3(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 map object.
.RE
.RS
The key and the value of each record are situated one after the other.
.RE
.RE
.PP
The function `tcmapdup' is used in order to copy a map object.
.PP
.RS
.br
\fBTCMAP *tcmapdup(const TCMAP *\fImap\fB);\fR
.RS
`\fImap\fR' specifies the map object.
.RE
.RS
The return value is the new map object equivalent to the specified object.
.RE
.RE
.PP
The function `tcmapdel' is used in order to delete a map object.
.PP
.RS
.br
\fBvoid tcmapdel(TCMAP *\fImap\fB);\fR
.RS
`\fImap\fR' specifies the map object.
.RE
.RS
Note that the deleted object and its derivatives can not be used anymore.
.RE
.RE
.PP
The function `tcmapput' is used in order to store a record into a map object.
.PP
.RS
.br
\fBvoid tcmapput(TCMAP *\fImap\fB, const void *\fIkbuf\fB, int \fIksiz\fB, const void *\fIvbuf\fB, int \fIvsiz\fB);\fR
.RS
`\fImap\fR' specifies the map object.
.RE
.RS
`\fIkbuf\fR' specifies the pointer to the region of the key.
.RE
.RS
`\fIksiz\fR' specifies the size of the region of the key.
.RE
.RS
`\fIvbuf\fR' specifies the pointer to the region of the value.
.RE
.RS
`\fIvsiz\fR' specifies the size of the region of the value.
.RE
.RS
If a record with the same key exists in the map, it is overwritten.
.RE
.RE
.PP
The function `tcmapput2' is used in order to store a string record into a map object.
.PP
.RS
.br
\fBvoid tcmapput2(TCMAP *\fImap\fB, const char *\fIkstr\fB, const char *\fIvstr\fB);\fR
.RS
`\fImap\fR' specifies the map object.
.RE
.RS
`\fIkstr\fR' specifies the string of the key.
.RE
.RS
`\fIvstr\fR' specifies the string of the value.
.RE
.RS
If a record with the same key exists in the map, it is overwritten.
.RE
.RE
.PP
The function `tcmapputkeep' is used in order to store a new record into a map object.
.PP
.RS
.br
\fBbool tcmapputkeep(TCMAP *\fImap\fB, const void *\fIkbuf\fB, int \fIksiz\fB, const void *\fIvbuf\fB, int \fIvsiz\fB);\fR
.RS
`\fImap\fR' specifies the map object.
.RE
.RS
`\fIkbuf\fR' specifies the pointer to the region of the key.
.RE
.RS
`\fIksiz\fR' specifies the size of the region of the key.
.RE
.RS
`\fIvbuf\fR' specifies the pointer to the region of the value.
.RE
.RS
`\fIvsiz\fR' specifies the size of the region of the value.
.RE
.RS