spex-en.html

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

<dl class="api">
<dt><code>void *tclistremove(TCLIST *<var>list</var>, int <var>index</var>, int *<var>sp</var>);</code></dt>
<dd>`<var>list</var>' specifies the list object.</dd>
<dd>`<var>index</var>' specifies the index of the element to be removed.</dd>
<dd>`<var>sp</var>' specifies the pointer to the variable into which the size of the region of the return value is assigned.</dd>
<dd>The return value is the pointer to the region of the removed element.</dd>
<dd>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'.</dd>
</dl>

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

<dl class="api">
<dt><code>char *tclistremove2(TCLIST *<var>list</var>, int <var>index</var>);</code></dt>
<dd>`<var>list</var>' specifies the list object.</dd>
<dd>`<var>index</var>' specifies the index of the element to be removed.</dd>
<dd>The return value is the string of the removed element.</dd>
<dd>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'.</dd>
</dl>

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

<dl class="api">
<dt><code>void tclistover(TCLIST *<var>list</var>, int <var>index</var>, const void *<var>ptr</var>, int <var>size</var>);</code></dt>
<dd>`<var>list</var>' specifies the list object.</dd>
<dd>`<var>index</var>' specifies the index of the element to be overwritten.</dd>
<dd>`<var>ptr</var>' specifies the pointer to the region of the new content.</dd>
<dd>`<var>size</var>' specifies the size of the new content.</dd>
<dd>If `index' is equal to or more than the number of elements, this function has no effect.</dd>
</dl>

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

<dl class="api">
<dt><code>void tclistover2(TCLIST *<var>list</var>, int <var>index</var>, const char *<var>str</var>);</code></dt>
<dd>`<var>list</var>' specifies the list object.</dd>
<dd>`<var>index</var>' specifies the index of the element to be overwritten.</dd>
<dd>`<var>str</var>' specifies the string of the new content.</dd>
<dd>If `index' is equal to or more than the number of elements, this function has no effect.</dd>
</dl>

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

<dl class="api">
<dt><code>void tclistsort(TCLIST *<var>list</var>);</code></dt>
<dd>`<var>list</var>' specifies the list object.</dd>
</dl>

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

<dl class="api">
<dt><code>int tclistlsearch(const TCLIST *<var>list</var>, const void *<var>ptr</var>, int <var>size</var>);</code></dt>
<dd>`<var>list</var>' specifies the list object.</dd>
<dd>`<var>ptr</var>' specifies the pointer to the region of the key.</dd>
<dd>`<var>size</var>' specifies the size of the region.</dd>
<dd>The return value is the index of a corresponding element or -1 if there is no corresponding element.</dd>
<dd>If two or more elements correspond, the former returns.</dd>
</dl>

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

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

<p>The function `tclistclear' is used in order to clear a list object.</p>

<dl class="api">
<dt><code>void tclistclear(TCLIST *<var>list</var>);</code></dt>
<dd>`<var>list</var>' specifies the list object.</dd>
<dd>All elements are removed.</dd>
</dl>

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

<dl class="api">
<dt><code>void *tclistdump(const TCLIST *<var>list</var>, int *<var>sp</var>);</code></dt>
<dd>`<var>list</var>' specifies the list object.</dd>
<dd>`<var>sp</var>' specifies the pointer to the variable into which the size of the region of the return value is assigned.</dd>
<dd>The return value is the pointer to the region of the result serial region.</dd>
<dd>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.</dd>
</dl>

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

<dl class="api">
<dt><code>TCLIST *tclistload(const void *<var>ptr</var>, int <var>size</var>);</code></dt>
<dd>`<var>ptr</var>' specifies the pointer to the region of serialized byte array.</dd>
<dd>`<var>size</var>' specifies the size of the region.</dd>
<dd>The return value is a new list object.</dd>
<dd>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.</dd>
</dl>

<h3 id="tcutilapi_mapapi">API of Hash Map</h3>

<p>The function `tcmapnew' is used in order to create a map object.</p>

<dl class="api">
<dt><code>TCMAP *tcmapnew(void);</code></dt>
<dd>The return value is the new map object.</dd>
</dl>

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

<dl class="api">
<dt><code>TCMAP *tcmapnew2(uint32_t <var>bnum</var>);</code></dt>
<dd>`<var>bnum</var>' specifies the number of the buckets.</dd>
<dd>The return value is the new map object.</dd>
</dl>

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

<dl class="api">
<dt><code>TCMAP *tcmapnew3(const char *<var>str</var>, ...);</code></dt>
<dd>`<var>str</var>' specifies the string of the first element.</dd>
<dd>The other arguments are other elements.  They should be trailed by a `NULL' argument.</dd>
<dd>The return value is the new map object.</dd>
<dd>The key and the value of each record are situated one after the other.</dd>
</dl>

<p>The function `tcmapdup' is used in order to copy a map object.</p>

<dl class="api">
<dt><code>TCMAP *tcmapdup(const TCMAP *<var>map</var>);</code></dt>
<dd>`<var>map</var>' specifies the map object.</dd>
<dd>The return value is the new map object equivalent to the specified object.</dd>
</dl>

<p>The function `tcmapdel' is used in order to delete a map object.</p>

<dl class="api">
<dt><code>void tcmapdel(TCMAP *<var>map</var>);</code></dt>
<dd>`<var>map</var>' specifies the map object.</dd>
<dd>Note that the deleted object and its derivatives can not be used anymore.</dd>
</dl>

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

<dl class="api">
<dt><code>void tcmapput(TCMAP *<var>map</var>, const void *<var>kbuf</var>, int <var>ksiz</var>, const void *<var>vbuf</var>, int <var>vsiz</var>);</code></dt>
<dd>`<var>map</var>' specifies the map object.</dd>
<dd>`<var>kbuf</var>' specifies the pointer to the region of the key.</dd>
<dd>`<var>ksiz</var>' specifies the size of the region of the key.</dd>
<dd>`<var>vbuf</var>' specifies the pointer to the region of the value.</dd>
<dd>`<var>vsiz</var>' specifies the size of the region of the value.</dd>
<dd>If a record with the same key exists in the map, it is overwritten.</dd>
</dl>

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

<dl class="api">
<dt><code>void tcmapput2(TCMAP *<var>map</var>, const char *<var>kstr</var>, const char *<var>vstr</var>);</code></dt>
<dd>`<var>map</var>' specifies the map object.</dd>
<dd>`<var>kstr</var>' specifies the string of the key.</dd>
<dd>`<var>vstr</var>' specifies the string of the value.</dd>
<dd>If a record with the same key exists in the map, it is overwritten.</dd>
</dl>

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

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

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

<dl class="api">
<dt><code>bool tcmapputkeep2(TCMAP *<var>map</var>, const char *<var>kstr</var>, const char *<var>vstr</var>);</code></dt>
<dd>`<var>map</var>' specifies the map object.</dd>
<dd>`<var>kstr</var>' specifies the string of the key.</dd>
<dd>`<var>vstr</var>' specifies the string of the value.</dd>
<dd>If successful, the return value is true, else, it is false.</dd>
<dd>If a record with the same key exists in the map, this function has no effect.</dd>
</dl>

<p>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.</p>

<dl class="api">
<dt><code>void tcmapputcat(TCMAP *<var>map</var>, const void *<var>kbuf</var>, int <var>ksiz</var>, const void *<var>vbuf</var>, int <var>vsiz</var>);</code></dt>
<dd>`<var>map</var>' specifies the map object.</dd>
<dd>`<var>kbuf</var>' specifies the pointer to the region of the key.</dd>
<dd>`<var>ksiz</var>' specifies the size of the region of the key.</dd>
<dd>`<var>vbuf</var>' specifies the pointer to the region of the value.</dd>
<dd>`<var>vsiz</var>' specifies the size of the region of the value.</dd>
<dd>If there is no corresponding record, a new record is created.</dd>
</dl>

<p>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.</p>

<dl class="api">
<dt><code>void tcmapputcat2(TCMAP *<var>map</var>, const char *<var>kstr</var>, const char *<var>vstr</var>);</code></dt>
<dd>`<var>map</var>' specifies the map object.</dd>
<dd>`<var>kstr</var>' specifies the string of the key.</dd>