Tokyo Cabinet第1版基本仕様書

Last Update: Sat, 08 Nov 2008 20:04:20 +0900

はじめに

Tokyo Cabinetはデータベースを扱うルーチン群のライブラリです。データベースといっても単純なもので、キーと値のペアからなるレコード群を格納したデータファイルです。キーと値は任意の長さを持つ一連のバイト列であり、文字列でもバイナリでも扱うことができます。テーブルやデータ型の概念はありません。レコードはハッシュ表かB+木か固定長配列で編成されます。

ハッシュ表のデータベースでは、キーはデータベース内で一意であり、キーが重複する複数のレコードを格納することはできません。このデータベースに対しては、キーと値を指定してレコードを格納したり、キーを指定して対応するレコードを削除したり、キーを指定して対応するレコードを検索したりすることができます。また、データベースに格納してある全てのキーを順不同に一つずつ取り出すこともできます。このような操作は、UNIX標準で定義されているDBMライブラリおよびその追従であるNDBMやGDBMに類するものです。Tokyo CabinetはDBMのより良い代替として利用することができます。

B+木のデータベースでは、キーが重複する複数のレコードを格納することができます。このデータベースに対しては、ハッシュ表のデータベースと同様に、キーを指定してレコードを格納したり取り出したり削除したりすることができます。レコードはユーザが指示した比較関数に基づいて整列されて格納されます。カーソルを用いて各レコードを昇順または降順で参照することができます。この機構によって、文字列の前方一致検索や数値の範囲検索が可能になります。また、B+木のデータベースではトランザクションが利用できます。

固定長配列のデータベースでは、一意な自然数をキーとしてレコードが格納されます。キーが重複する複数のレコードを格納することはできません。また、各レコードの値の長さは一定以下に制限されます。提供される操作はハッシュデータベースとほぼ同様です。

Tokyo CabinetはC言語で記述され、CとPerlとRubyとJavaとLuaのAPIとして提供されます。Tokyo CabinetはC99およびPOSIX準拠のAPIを備えるプラットフォームで利用できます。Tokyo CabinetはGNU Lesser General Public Licenseに基づくフリーソフトウェアです。

特徴

Tokyo CabinetはQDBMの後継であり、空間効率と時間効率と使いやすさを向上させた製品です。この節ではTokyo Cabinetの特徴について説明します。

DBM一族の最右翼

Tokyo CabinetはGDBMやQDBMの後継として次の点を目標として開発されました。これらの目標は達成されており、Tokyo Cabinetは従来のDBMを置き換える製品だと言えます。

時間効率の向上 : データベースファイルがより小さい
空間効率の向上 : 処理がより高速である
並列性の向上 : マルチスレッド環境での同時実行性能の向上
利便性の向上 : APIがより単純である
堅牢性の向上 : 不慮の事態でもデータベースファイルが壊れにくい
64ビット対応 : 巨大なメモリ空間とデータベースファイルを扱える

Tokyo CabinetはQDBMと同様に、伝統的なDBMが抱える三つの制限事項を回避しています。すなわち、プロセス内で複数のデータベースを扱うことができ、キーと値のサイズに制限がなく、データベースファイルがスパースではありません。さらに、QDBMが抱える三つの制限事項を回避しています。すなわち、2GB以上のデータベースファイルを扱うことができ、バイトオーダの異なる環境間でデータベースファイルを共有することができ、複数のスレッドが同時にデータベースの探索を行うことができます。

Tokyo Cabinetは高速に動作します。例えば100万件のレコードの登録にかかる時間は、ハッシュデータベースで0.7秒ほど、B+木データベースで1.6秒ほどです。そしてTokyo Cabinetのデータベースは小さいです。例えば1レコードあたりのオーバーヘッドは、ハッシュデータベースで16バイトほど、B+木データベースで5バイトほどです。さらにTokyo Cabinetで扱えるデータの規模は莫大です。最大8EB（9.22e18バイト）までのデータベースファイルを扱うことができます。

効率的なハッシュデータベースの実装

Tokyo Cabinetはレコードの探索にハッシュアルゴリズムを用います。バケット配列に十分な要素数があれば、レコードの探索にかかる時間計算量は O(1) です。すなわち、レコードの探索に必要な時間はデータベースの規模に関わらず一定です。追加や削除に関しても同様です。ハッシュ値の衝突はセパレートチェーン法で管理します。チェーンのデータ構造は二分探索木です。したがって、バケット配列の要素数が著しく少ない場合でも、探索等の時間計算量は O(log n) に抑えられます。

Tokyo Cabinetはバケット配列を全てRAM上に保持することによって、処理の高速化を図ります。バケット配列がRAM上にあれば、ほぼ1パスのファイル操作でレコードに該当するファイル上の領域を参照することができます。ファイルに記録されたバケット配列は `read' コールでRAM上に読み込むのではなく、`mmap' コールでRAMに直接マッピングされます。したがって、データベースに接続する際の準備時間が極めて短く、また、複数のプロセスでメモリマップを共有することができます。

バケット配列の要素数が格納するレコード数の半分ほどであれば、データの性質によって多少前後しますが、ハッシュ値の衝突率は56.7%ほどです（等倍だと36.8%、2倍だと21.3%、4倍だと11.5%、8倍だと6.0%ほど）。そのような場合、平均2パス以下のファイル操作でレコードを探索することができます。これを性能指標とするならば、例えば100万個のレコードを格納するためには50万要素のバケット配列が求められます。バケット配列の各要素は4バイトです。すなわち、2MバイトのRAMが利用できれば100万レコードのデータベースが構築できます。

伝統的なDBMにはレコードの追加操作に関して「挿入」モードと「置換」モードがあります。前者では、キーが既存のレコードと重複する際に既存の値を残します。後者では、キーが既存のレコードと重複した際に新しい値に置き換えます。Tokyo Cabinetはその２つに加えて「連結」モードがあります。既存の値の末尾に指定された値を連結して格納する操作です。レコードの値を配列として扱う場合、要素を追加するには連結モードが役に立ちます。

一般的に、データベースの更新処理を続けるとファイル内の利用可能領域の断片化が起き、ファイルのサイズが肥大化してしまいます。Tokyo Cabinetは隣接する不要領域を連結して再利用し、またデータベースの最適化機能を備えることによってこの問題に対処します。既存のレコードの値をより大きなサイズの値に上書きする場合、そのレコードの領域をファイル中の別の位置に移動させる必要があります。この処理の時間計算量はレコードのサイズに依存するので、値を拡張していく場合には効率が悪くなります。しかし、Tokyo Cabinetはアラインメントによってこの問題に対処します。増分がパディングに収まれば領域を移動させる必要はありません。

便利なB+木データベースの実装

B+木データベースはハッシュデータベースより遅いのですが、ユーザが定義した順序に基づいて各レコードを参照できることが特長です。B+木は複数のレコードを整列させた状態で論理的なページにまとめて管理します。各ページに対してはB木すなわち多進平衡木によって階層化された疎インデックスが維持されます。したがって、各レコードの探索等にかかる時間計算量は O(log n) です。各レコードを順番に参照するためにカーソルが提供されます。カーソルの場所はキーを指定して飛ばすことができ、また現在の場所から次のレコードに進めたり前のレコードに戻したりすることができます。各ページは双方向リンクリストで編成されるので、カーソルを前後に移動させる操作の時間計算量は O(1) です。

B+木データベースは上述のハッシュデータベースを基盤として実装されます。B+木の各ページはハッシュデータベースのレコードとして記録されるので、ハッシュデータベースの記憶管理の効率性を継承しています。B+木では各レコードのヘッダが小さく、アラインメントはページの単位でとられるので、ほとんどの場合、ハッシュデータベースに較べてデータベースファイルのサイズが半減します。B+木を更新する際には多くのページを操作する必要がありますが、Tokyo Cabinetはページをキャッシュすることによってファイル操作を減らして処理を効率化します。ほとんどの場合、疎インデックス全体がメモリ上にキャッシュされるので、各レコードを参照するのに必要なファイル操作は平均1パス以下です。

B+木データベースはトランザクション機構を提供します。トランザクションを開始してから終了するまでの一連の操作を一括してデータベースにコミットしたり、一連の更新操作を破棄してデータベースの状態をトランザクションの開始前の状態にロールバックしたりすることができます。トランザクションの分離レベルは2種類あります。データベースに対する全ての操作をトランザクション内で行うと直列化可能（serializable）トランザクションとなり、トランザクション外の操作を同時に行うと非コミット読み取り（read uncommitted）トランザクションとなります。

各ページを圧縮して保存する機能も提供されます。圧縮方式はZLIBのDeflateとBZIP2のブロックソーティングの2種類をサポートしています。同一ページ内の各レコードは似たようなパターンを持つため、Lempel-ZivやBWTなどのアルゴリズムを適用すると高い圧縮効率が期待できます。テキストデータを扱う場合、データベースのサイズが元の25%程度になります。データベースの規模が大きくディスクI/Oがボトルネックとなる場合は、圧縮機能を有効化すると処理速度が大幅に改善されます。

素朴な固定長データベースの実装

固定長データベースは、キーが自然数でなくてはならず、また値のサイズが制限されますが、その条件を受諾できる場合には最も効率的です。レコード群は固定長の要素の配列として保持され、各レコードはキーの倍数から算出されるオフセットの位置に格納されます。したがって、各レコードの探索等にかかる時間計算量は O(1) です。提供される操作群はハッシュデータベースとほぼ同じです。

データベース全体を `mmap' コールでメモリ上にマッピングして多次元配列として参照するので、ファイルI/Oにかかるオーバーヘッドは極小化されます。構造が単純なおかげで、固定長データベースはハッシュデータベースよりもさらに高速に動作するとともに、マルチスレッド環境での並列実行性能も傑出しています。

データベースのサイズは、キーの変域と値の制限長に比例します。すなわち、キーの変域が小さく、値のサイズが小さいほど、空間効率は向上します。例えば、キーの最大値が100万で、値の制限長が100バイトの場合、データベースのサイズは100MBほどになります。RAM上に読み込まれるのは実際に参照されたレコードの周辺の領域のみなので、データベースのサイズは仮想メモリのサイズまで大きくすることができます。

単純だが多様なインタフェース群

Tokyo Cabinetはオブジェクト指向に基づいた簡潔なAPIを提供します。データベースに対する全ての操作はデータベースオブジェクトにカプセル化され、開く（open）、閉じる（close）、挿入する（put）、削除する（out）、取得する（get）といった関数（メソッド）を呼ぶことでプログラミングを進めていけます。ハッシュデータベースとB+木データベースと固定長データベースのAPIは互いに酷似しているので、アプリケーションを一方から他方に移植することも簡単です。

Tokyo Cabinetにはデータベースに接続するモードとして、「リーダ」と「ライタ」の二種類があります。リーダは読み込み専用で、ライタは読み書き両用です。データベースにはファイルロックによってプロセス間での排他制御が行われます。ライタが接続している間は、他のプロセスはリーダとしてもライタとしても接続できません。リーダが接続している間は、他のプロセスのリーダは接続できるが、ライタは接続できません。この機構によって、マルチタスク環境での同時接続に伴うデータの整合性が保証されます。

Tokyo CabinetのAPIの各関数はリエントラントであり、マルチスレッド環境で安全に利用することができます。別個のデータベースオブジェクトに対しては全ての操作を完全に並列に行うことができます。同一のデータベースオブジェクトに対しては、リードライトロックで排他制御を行います。すなわち、読み込みを行うスレッド同士は並列に実行でき、書き込みを行うスレッドは他の読み込みや書き込みをブロックします。

メモリ上でレコードを簡単に扱うために、ユーティリティAPIが提供されます。リストやマップといった基本的なデータ構造をはじめ、メモリプールや文字列処理や符号処理など、プログラミングで良く使う機能を詰め込んでいます。

C言語のAPIには、ユーティリティAPI、ハッシュデータベースAPI、B+木データベースAPI、固定長データベースAPI、抽象データベースAPIの5種類があります。各APIに対応したコマンドラインインタフェースも用意されています。それらはプロトタイピングやテストやデバッグなどで活躍するでしょう。Tokyo CabinetはC言語の他にも、PerlとRubyとJavaとLuaのAPIを提供します。Perl用APIはXS言語を用いてハッシュデータベースAPIとB+木データベースAPIと固定長データベースAPIを呼び出すものです。Ruby用APIはRubyのモジュールとしてハッシュデータベースAPIとB+木データベースAPIと固定長データベースAPIを呼び出すものです。Java用APIはJava Native Interfaceを用いてハッシュデータベースAPIとB+木データベースAPIと固定長データベースAPIを呼び出すものです。Lua用APIはLuaのモジュールとしてハッシュデータベースAPIとB+木データベースAPIと固定長データベースAPIを呼び出すものです。その他の言語のインターフェイスも第三者によって提供されるでしょう。

複数のプロセスが同時にデータベースを操作したい場合やリモートホストにあるデータベースを操作したい場合には、リモートサービスを使うと便利です。リモートサービスはデータベースサーバとそのアクセスライブラリからなり、アプリケーションはリモートデータベースAPIを介してデータベースサーバを操作することができます。HTTPやmemcachedプロトコルもサポートするので、ほぼ全てのプラットフォームからデータベースサーバを簡単に操作することができます。

インストール

Tokyo Cabinetのソースパッケージからのインストール方法を説明します。バイナリパッケージのインストール方法についてはそれぞれのパッケージの説明書をご覧ください。

前提

Tokyo Cabinetの現在バージョンは、UNIX系のOSで利用することができます。少なくとも、以下の環境では動作するはずです。

Linux 2.4以降 (x86-32/x86-64/PowerPC/Alpha/SPARC)
Mac OS X 10.3以降 (x86-32/x86-64/PowerPC)

ソースパッケージを用いてTokyo Cabinetをインストールするには、gccのバージョン3.1以降とmakeが必要です。それらはLinuxやFreeBSDなどには標準的にインストールされています。

Tokyo Cabinetは、以下のライブラリを利用しています。予めインストールしておいてください。

zlib : 可逆データ圧縮。バージョン1.2.3以降推奨。
bzip2 : 可逆データ圧縮。バージョン1.0.5以降推奨。

ビルドとインストール

Tokyo Cabinetの配布用アーカイブファイルを展開したら、作成されたディレクトリに入ってインストール作業を行います。

configureスクリプトを実行して、ビルド環境を設定します。

./configure

プログラムをビルドします。

make

プログラムの自己診断テストを行います。

make check

プログラムをインストールします。作業はrootユーザで行います。

make install

結果

一連の作業が終ると、以下のファイルがインストールされます。

/usr/local/include/tcutil.h
/usr/local/include/tchdb.h
/usr/local/include/tcbdb.h
/usr/local/include/tcfdb.h
/usr/local/include/tcadb.h
/usr/local/lib/libtokyocabinet.a
/usr/local/lib/libtokyocabinet.so.5.12.0
/usr/local/lib/libtokyocabinet.so.5
/usr/local/lib/libtokyocabinet.so
/usr/local/lib/pkgconfig/tokyocabinet.pc
/usr/local/bin/tcutest
/usr/local/bin/tcumttest
/usr/local/bin/tcucodec
/usr/local/bin/tchtest
/usr/local/bin/tchmttest
/usr/local/bin/tchmgr
/usr/local/bin/tcbmgr
/usr/local/bin/tcbtest
/usr/local/bin/tcbmttest
/usr/local/bin/tcftest
/usr/local/bin/tcfmttest
/usr/local/bin/tcfmgr
/usr/local/bin/tcamgr
/usr/local/bin/tcatest
/usr/local/libexec/tcawmgr.cgi
/usr/local/share/tokyocabinet/...
/usr/local/man/man1/...
/usr/local/man/man3/...

configureのオプション

「./configure」を実行する際には、以下のオプションを指定することができます。

--enable-debug : デバッグ用にビルドする。デバッグシンボルを有効化し、最適化を行わず、静的にリンクする。
--enable-devel : 開発用にビルドする。デバッグシンボルを有効化し、最適化を行い、動的にリンクする。
--enable-profile : プロファイル用にビルドする。プロファイルオプションを有効化し、最適化を行い、動的にリンクする。
--enable-static : 静的にリンクする。
--enable-fastest : 最高速になるように最適化を行う。
--enable-off64 : 32ビット環境でも64ビットのファイルオフセットを用いる。
--enable-swab : バイトオーダの変換を強制する。
--enable-uyield : レースコンディションの検出用にビルドする。
--disable-zlib : ZLIBによるレコード圧縮を無効にする。
--disable-bzip : BZIP2によるレコード圧縮を無効にする。
--disable-pthread : POSIXスレッドのサポートを無効にする。
--disable-shared : 共有ライブラリのビルドを行わない。

`--prefix' などのオプションも一般的なUNIXソフトウェアのパッケージと同様に利用可能です。`/usr/local' 以下ではなく '/usr' 以下にインストールしたい場合は `--prefix=/usr' を指定してください。なお、ライブラリ検索パスに `/usr/local/lib' が入っていない環境では、Tokyo Cabinetのアプリケーションを実行する際に環境変数 `LD_LIBRARY_PATH' の値に `/usr/local/lib' を含めておくようにしてください。

ライブラリの使い方

Tokyo CabinetはC言語のAPIを提供し、それはC89標準（ANSI C）またはC99標準に準拠したプログラムから利用することができます。Tokyo Cabinetヘッダは `tcutil.h'、`tchdb.h'、`tcbdb.h'、`tcadb.h' として提供されますので、適宜それらをアプリケーションのソースコード中でインクルードした上で、APIの各種機能を利用してください。ライブラリは `libtokyocabinet.a' および `libtokyocabinet.so' として提供され、それらは `libz.so'、`libpthread.so'、`libm.so'、`libc.so' に依存しますので、アプリケーションプログラムをビルドする際のリンカオプションには `-ltokyocabinet'、`-lz'、`-lbz2'、`-lpthread'、`-lm'、`-lc' を加えてください。最も典型的なビルド手順は以下のようになります。

gcc -I/usr/local/include tc_example.c -o tc_example \
  -L/usr/local/lib -ltokyocabinet -lz -lbz2 -lpthread -lm -lc

Tokyo CabinetはC++言語のプログラムからも利用することができます。各ヘッダは暗黙的にCリンケージ（「extern "C"」ブロック）で包まれているので、単にインクルードするだけで利用することができます。

ユーティリティAPI

ユーティリティAPIは、メモリ上で簡単にレコードを扱うためのルーチン集です。特に拡張可能文字列と配列リストがハッシュマップと順序木が便利です。`tcutil.h' にAPIの仕様の完全な記述があります。

概要

ユーティリティAPIを使うためには、`tcutil.h' および関連する標準ヘッダファイルをインクルードしてください。通常、ソースファイルの冒頭付近で以下の記述を行います。

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

拡張可能文字列を扱う際には、`TCXSTR' 型へのポインタをオブジェクトとして用います。拡張可能文字列オブジェクトは、関数 `tcxstrnew' で作成し、関数 `tcxstrdel' で破棄します。配列リストを扱う際には、`TCLIST' 型へのポインタをオブジェクトとして用います。リストオブジェクトは、関数 `tclistnew' で作成し、関数 `tclistdel' で破棄します。ハッシュマップを扱う際には、`TCMAP' 型へのポインタをオブジェクトとして用います。マップオブジェクトは、関数 `tcmapopen' で作成し、関数 `tcmapdel' で破棄します。順序木を扱う際には、`TCTREE' 型へのポインタをオブジェクトとして用います。ツリーオブジェクトは、関数 `tctreeopen' で作成し、関数 `tctreedel' で破棄します。作成したオブジェクトを使い終わったら必ず破棄してください。そうしないとメモリリークが発生します。

基礎的なユーティリティのAPI（英語御免）

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

extern const char *tcversion;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

拡張可能文字列のAPI（英語御免）

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The function `tcxstrtomalloc' is used in order to convert an extensible string object into a usual allocated region.

void *tcxstrtomalloc(TCXSTR *xstr);: `xstr' specifies the extensible string object.; The return value is the pointer to the allocated 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. 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. Because the region of the original object is deleted, it should not be deleted again.

The function `tcxstrfrommalloc' is used in order to create an extensible string object from an allocated region.

TCXSTR *tcxstrfrommalloc(void *ptr, int size);: `ptr' specifies the pointer to the region allocated with `malloc' call.; `size' specifies the size of the region.; The return value is the new extensible string object wrapping the specified region.; Note that the specified region is released when the object is deleted.

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

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

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

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

配列リストのAPI（英語御免）

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 `tclistdup' is used in order to copy a list object.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void tclistpushmalloc(TCLIST *list, void *ptr, int size);: `list' specifies the list object.; `ptr' specifies the pointer to the region allocated with `malloc' call.; `size' specifies the size of the region.; Note that the specified region is released when the object is deleted.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The function `tclistsortci' is used in order to sort elements of a list object in case-insensitive lexical order.

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

The function `tclistsortex' is used in order to sort elements of a list object by an arbitrary comparison function.

void tclistsortex(TCLIST *list, int (*cmp)(const TCLISTDATUM *, const TCLISTDATUM *));: `list' specifies the list object.; `cmp' specifies the pointer to the comparison function. The structure `TCLISTDATUM' has the member "ptr" which is the pointer to the region of the element, and the member "size" which is the size of the region.

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（英語御免）

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 `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 `tcmapput3' is used in order to store a record of the value of two regions into a map object.

void tcmapput3(TCMAP *map, const void *kbuf, int ksiz, const void *fvbuf, int fvsiz, const void *lvbuf, int lvsiz);: `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.; `fvbuf' specifies the pointer to the former region of the value.; `fvsiz' specifies the size of the former region of the value.; `lvbuf' specifies the pointer to the latter region of the value.; `lvsiz' specifies the size of the latter region of the value.; If a record with the same key exists in the map, it is overwritten.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

const void *tcmapget3(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 internal region of the returned record is moved to the tail so that the record will survive for a time under LRU cache algorithm removing records from the head.

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 head if it is true or 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 head if it is true or tail if else.; If successful, the return value is true. False is returned when no record corresponds to the specified key.

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

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

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

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

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

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

The function `tcmapiterval' is used in order to get the value bound to the key fetched from the iterator of a map object.

const void *tcmapiterval(const void *kbuf, int *sp);: `kbuf' specifies the pointer to the region of the iteration key.; `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 of the corresponding record.; 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 `tcmapiterval2' is used in order to get the value string bound to the key fetched from the iterator of a map object.

const char *tcmapiterval2(const char *kstr);: `kstr' specifies the string of the iteration key.; The return value is the pointer to the region of the value of the corresponding record.

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

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

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

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

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

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

The function `tcmapkeys2' is used in order to create an array of strings of all keys in a map object.

const char **tcmapkeys2(const TCMAP *map, int *np);: `map' specifies the map object.; `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 all string keys in the map object.; 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. Note that elements of the array point to the inner objects, whose life duration is synchronous with the map object.

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

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

The function `tcmapvals2' is used in order to create an array of strings of all values in a map object.

const char **tcmapvals2(const TCMAP *map, int *np);: `map' specifies the map object.; `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 all string values in the map object.; 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. Note that elements of the array point to the inner objects, whose life duration is synchronous with the map object.

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

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

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

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

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

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

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

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

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

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

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

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

The function `tcmaploadone' is used in order to extract a map record from a serialized byte array.

void *tcmaploadone(const void *ptr, int size, const void *kbuf, int ksiz, int *sp);: `ptr' specifies the pointer to the region of serialized byte array.; `size' specifies the size of the region.; `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.

順序木のAPI（英語御免）

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(TREECMP 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 tree object.; The default comparison function compares keys of two records by lexical order. The functions `tctreecmplexical' (dafault), `tctreecmpdecimal', `tctreecmpint32', and `tctreecmpint64' are built-in.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The function `tctreeget3' is used in order to retrieve a record in a tree object without balancing nodes.

const void *tctreeget3(const 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 `tctreeiterinit' is used in order to initialize the iterator of a tree object.

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

The function `tctreeiterinit2' is used in order to initialize the iterator of a tree object in front of records corresponding a key.

void tctreeiterinit2(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.; The iterator is set to the first record corresponding the key or the next substitute if completely matching record does not exist.

The function `tctreeiterinit3' is used in order to initialize the iterator of a tree object in front of records corresponding a key string.

void tctreeiterinit3(TCTREE *tree, const char *kstr);: `tree' specifies the tree object.; `kstr' specifies the string of the key.; The iterator is set to the first record corresponding the key or the next substitute if completely matching record does not exist.

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 `tctreeiterval' is used in order to get the value bound to the key fetched from the iterator of a tree object.

const void *tctreeiterval(const void *kbuf, int *sp);: `kbuf' specifies the pointer to the region of the iteration key.; `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 of the corresponding record.; 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 `tctreeiterval2' is used in order to get the value string bound to the key fetched from the iterator of a tree object.

const char *tctreeiterval2(const char *kstr);: `kstr' specifies the string of the iteration key.; The return value is the pointer to the region of the value of the corresponding record.

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

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

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

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

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

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

The function `tctreekeys2' is used in order to create an array of strings of all keys in a tree object.

const char **tctreekeys2(const TCTREE *tree, int *np);: `tree' specifies the tree object.; `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 all string keys in the tree object.; 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. Note that elements of the array point to the inner objects, whose life duration is synchronous with the tree object.

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

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

The function `tctreevals2' is used in order to create an array of strings of all values in a tree object.

const char **tctreevals2(const TCTREE *tree, int *np);: `tree' specifies the tree object.; `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 all string values in the tree object.; 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. Note that elements of the array point to the inner objects, whose life duration is synchronous with the tree object.

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

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

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

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

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

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

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

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

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

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

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

TCTREE *tctreeload(const void *ptr, int size, TREECMP 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.

The function `tctreeloadone' is used in order to extract a tree record from a serialized byte array.

void *tctreeloadone(const void *ptr, int size, const void *kbuf, int ksiz, int *sp);: `ptr' specifies the pointer to the region of serialized byte array.; `size' specifies the size of the region.; `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.

オンメモリハッシュデータベースのAPI（英語御免）

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 `tcmdbput3' is used in order to store a record of the value of two regions into an on-memory hash database object.

void tcmdbput3(TCMDB *mdb, const void *kbuf, int ksiz, const void *fvbuf, int fvsiz, const void *lvbuf, int lvsiz);: `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.; `fvbuf' specifies the pointer to the former region of the value.; `fvsiz' specifies the size of the former region of the value.; `lvbuf' specifies the pointer to the latter region of the value.; `lvsiz' specifies the size of the latter region of the value.; If a record with the same key exists in the database, it is overwritten.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The function `tcmdbget3' is used in order to retrieve a record and move it astern in an on-memory hash database object.

void *tcmdbget3(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 internal region of the returned record is moved to the tail so that the record will survive for a time under LRU cache algorithm removing records from the head.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

オンメモリツリーデータベースのAPI（英語御免）

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(TREECMP 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 `tctreecmplexical' (dafault), `tctreecmpdecimal', `tctreecmpint32', and `tctreecmpint64' are built-in. The object can be shared by plural threads because of the internal mutex.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The function `tcndbget3' is used in order to retrieve a record and move it astern in an on-memory tree database object.

void *tcndbget3(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 internal region of the returned record is moved to the tail so that the record will survive for a time under LRU cache algorithm removing records from the head.

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

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

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

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

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

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

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

void tcndbiterinit2(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.; The iterator is set to the first record corresponding the key or the next substitute if completely matching record does not exist.

The function `tcndbiterinit3' is used in order to initialize the iterator of an on-memory tree database object in front of a key string.

void tcndbiterinit3(TCNDB *ndb, const char *kstr);: `ndb' specifies the on-memory tree database object.; `kstr' specifies the string of the key.; The iterator is set to the first record corresponding the key or the next substitute if completely matching record does not exist.

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 and return 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 and return an empty list even if no key corresponds.; Because the object of the return value is created with the function `tclistnew', it should be deleted with the function `tclistdel' when it is no longer in use.

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

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

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

uint64_t tcndbmsiz(TCNDB *ndb);: `ndb' specifies the on-memory tree database object.; The retur