Tokyo Cabinet

Tokyo Cabinet is a library of routines for managing a database. the database is a simple data file containing records, each is a pair of a key and a value. every key and value is serial bytes with variable length. both binary data and character string can be used as a key and a value. there is neither concept of data tables nor data types. records are organized in

• hash table
• B+ tree

the following access methods are provided to the database:

• storing a record with a key and a value
• deleting a record by a key
• retrieving a record by a key
• traversal access to every key

as for database of fixed-length array, records are stored with unique natural numbers (thought the keys can contain underscore "_" , defis "-" , comma "," , point "." , questionmark "?" - all of them will be converted into empty). the length of each record is limited by the specified length. provided operations are the same as ones of hash database

Tokyo Cabinet is written in the C language, and provided as API of C89 (ANSI)/C99, Perl, Ruby, and Lua. Tokyo Cabinet is available on platforms which have API conforming to C99 and POSIX

like BerkeleyDB, TC gives you low-level database operations and allows you to build your own very fast data access operations. unlike BerkeleyDB, TC has several functional layers on top of TC which provide

• network access,
• schema-less document-oriented storage (a la CouchDB) and
• supported bindings for many languages

Tokyo Cabinet provides two modes to connect to a database: "reader" and "writer"

a "reader" can perform retrieving but neither storing nor deleting. a "writer" can perform all access methods

exclusion control between processes is performed when connecting to a database by file locking

while a "writer" is connected to a database, neither "readers" nor "writers" can be connected

while a "reader" is connected to a database, other "readers" can be connect, but "writers" can not

CLI

$> ttserver -host 127.0.0.1 -port 9000 /home/user/work/testdb.tch 
2019-06-23T07:47:40Z  SYSTEM  --------- logging started [7267] --------
2019-06-23T07:47:40Z  SYSTEM  server configuration: host=127.0.0.1 port=9000
2019-06-23T07:47:40Z  SYSTEM  maximum connection: 4095
2019-06-23T07:47:40Z  SYSTEM  opening the database: /home/user/work/testdb.tch
2019-06-23T07:47:40Z  SYSTEM  service started: 7267
2019-06-23T07:47:40Z  INFO  timer thread 1 started
2019-06-23T07:47:40Z  INFO  worker thread 1 started
2019-06-23T07:47:40Z  INFO  worker thread 2 started
2019-06-23T07:47:40Z  INFO  worker thread 3 started
2019-06-23T07:47:40Z  INFO  worker thread 4 started
2019-06-23T07:47:40Z  INFO  worker thread 5 started
2019-06-23T07:47:40Z  INFO  worker thread 6 started
2019-06-23T07:47:40Z  INFO  worker thread 7 started
2019-06-23T07:47:40Z  INFO  worker thread 8 started
2019-06-23T07:47:40Z  SYSTEM  listening started

$> tcrmgr version -port 9000 localhost 
Tokyo Tyrant version 1.1.41 (324:0.91) for Linux
Copyright (C) 2007-2010 Mikio Hirabayashi

$> tcrmgr get -port 9000 localhost key1
2019-06-23T07:48:26Z  INFO  connected: 127.0.0.1:38850
value1 12 3.14 
2019-06-23T07:48:26Z  INFO  connection finished

$> for y in key1 key2 ; do tcrmgr get -port 9000 localhost $y | cat | while read -a x ; do echo ${x[2]} ; done ; done
3.14
2.72

tcrmgr - CLI of the remote database

  $> time for x in {1..2000}; do tcrmgr get localhost somekey ; done

  $> ttserver -host 127.0.0.1 -port 9000 /path/to/your/database/yourdbname.tch
  $> tcrmgr get -port 9000 localhost yourkeyid 

you can delete all records of your database via tokyotyrant with the vanish command, e.g

  $> tcrmgr vanish [-port num] host

tchmgr - CLI for hash database

$> tchmgr version
Tokyo Cabinet version 1.4.48 (911:1.0) for Linux
Copyright (C) 2006-2012 FAL Labs




            tc  - "tokyo cabinet"
            h   - h-hash
            mgr - manager


        `path'   the path of a database file
        `bnum'   the number of buckets
        `apow'   the power of the alignment
        `key'    the key of a record
        `value'  the value of a record


 tchmgr create [-tl] [-td|-tb|-tt|-tx] path [bnum [apow [fpow]]]
        Create a database file.

 tchmgr put [-nl|-nb] [-sx] [-dk|-dc|-dai|-dad] path key value
        Store a record.

 tchmgr out [-nl|-nb] [-sx] path key
        Remove a record.

 tchmgr get [-nl|-nb] [-sx] [-px] [-pz] path key
        Print the value of a record.

 tchmgr list [-nl|-nb] [-m num] [-pv] [-px] [-fm str] path
        Print keys of all records, separated by line feeds.

 tchmgr optimize [-tl] [-td|-tb|-tt|-tx] [-tz] [-nl|-nb] [-df] path [bnum [apow [fpow]]]
        Optimize a database file.


options:
              -tl : enable the option `HDBTLARGE'.
              -td : enable the option `HDBTDEFLATE'.
              -tb : enable the option `HDBTBZIP'.
              -tt : enable the option `HDBTTCBS'.
              -tx : enable the option `HDBTEXCODEC'.
              -nl : enable the option `HDBNOLCK'.
              -nb : enable the option `HDBLCKNB'.
              -sx : the input data is evaluated as a hexadecimal data string.
              -dk : use the function `tchdbputkeep' instead of `tchdbput'.
              -dc : use the function `tchdbputcat' instead of `tchdbput'.
              -dai : use the function `tchdbaddint' instead of `tchdbput'.
              -dad : use the function `tchdbadddouble' instead of `tchdbput'.
              -px : the output data is converted into a hexadecimal data string.
              -pz : do not append line feed at the end of the output.
              -m num : specify the maximum number of the output.
              -pv : print values of records also.
              -fm str : specify the prefix of keys.
              -tz : enable the option `UINT8_MAX'.
              -df : perform defragmentation only.
              -sc : normalize keys as lower cases.
 

tcbmgr - CLI for B+ tree database

$> tcbmgr version
Tokyo Cabinet version 1.4.48 (911:1.0) for Linux
Copyright (C) 2006-2012 FAL Labs



            tc  - "tokyo cabinet"
            b   - b-tree
            mgr - manager


        `path'   the path of a database file
        `lmemb'  the number of members in each leaf page
        `nmemb'  the number of members in each non-leaf page
        `bnum'   the number of buckets
        `apow'   the power of the alignment
        `fpow'   the power of the free block pool
        `key'    the key of a record
        `value'  the value of a record


tcbmgr create [-cd|-ci|-cj] [-tl] [-td|-tb|-tt|-tx] path [lmemb [nmemb [bnum [apow [fpow]]]]]
Create a database file

tcbmgr put [-cd|-ci|-cj] [-nl|-nb] [-sx] [-dk|-dc|-dd|-db|-dai|-dad] path key value
Store a record

tcbmgr out [-cd|-ci|-cj] [-nl|-nb] [-sx] path key
Remove a record

tcbmgr get [-cd|-ci|-cj] [-nl|-nb] [-sx] [-px] [-pz] path key
Print the value of a record

tcbmgr list [-cd|-ci|-cj] [-nl|-nb] [-m num] [-bk] [-pv] [-px] [-j str] [-rb bkey ekey] [-fm str] path
Print keys of all records, separated by line feeds

tcbmgr optimize [-cd|-ci|-cj] [-tl] [-td|-tb|-tt|-tx] [-tz] [-nl|-nb] [-df] path
   [lmemb [nmemb [bnum [apow [fpow]]]]]
Optimize a database file


options:
        -cd           : use the comparison function `tccmpdecimal'
        -ci           : use the comparison function `tccmpint32'
        -cj           : use the comparison function `tccmpint64'
        -tl           : enable the option `BDBTLARGE'
        -td           : enable the option `BDBTDEFLATE'
        -tb           : enable the option `BDBTBZIP'
        -tt           : enable the option `BDBTTCBS'
        -tx           : enable the option `BDBTEXCODEC'
        -nl           : enable the option `BDBNOLCK'
        -nb           : enable the option `BDBLCKNB'
        -sx           : the input data is evaluated as a hexadecimal data string
        -dk           : use the function `tcbdbputkeep' instead of `tcbdbput'
        -dc           : use the function `tcbdbputcat' instead of `tcbdbput'
        -dd           : use the function `tcbdbputdup' instead of `tcbdbput'
        -db           : use the function `tcbdbputdupback' instead of `tcbdbput'
        -dai          : use the function `tcbdbaddint' instead of `tcbdbput'
        -dad          : use the function `tcbdbadddouble' instead of `tcbdbput'
        -px           : the output data is converted into a hexadecimal data string
        -pz           : do not append line feed at the end of the output
        -m num        : specify the maximum number of the output
        -bk           : perform backword scanning
        -pv           : print values of records also
        -j str        : specify the key where the cursor jump to
        -rb bkey ekey : specify the range of keys
        -fm str       : specify the prefix of keys
        -tz           : enable the option `UINT8_MAX'
        -df           : perform defragmentation only
        -sc           : normalize keys as lower cases

C-API

as the header files of Tokyo Cabinet are provided as 'tcutil.h', 'tchdb.h', and `tcbdb.h', applications should include one of them

the library is provided as 'libtokyocabinet.a' and `libtokyocabinet.so' and they depends on:
libz.so
librt.so
libpthread.so
libm.so
libc.so

linker options `-ltokyocabinet', `-lz', '-lbz2', `-lrt', `-lpthread', '-lm', and '-lc' are required for build command. A typical build command is the following

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

you can also use Tokyo Cabinet in programs written in C++. because each header is wrapped in C linkage ('extern "C"' block), you can simply include them into your C++ programs

example:

/*    gcc -ltokyocabinet treatment.c -o z.out            */

#include <tchdb.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

int fold   = 0 ;
int check  = 0 ;
int call   = 0 ;
int bet    = 0 ;
int allin  = 0 ;

typedef struct {
  char *nick   ;
  char *move ;
} keyValue ;

typedef keyValue* Step ;

void 
calcMoves (char* oneMove) 
{
  if      ( 0 == strcmp ("folds",  oneMove) )        { fold++ ;  } 
  else if ( 0 == strcmp ("checks", oneMove) )        { check++ ; } 
  else if ( 0 == strcmp ("calls",  oneMove) )        { call++ ;  } 
  else if ( 0 == strcmp ("bets",   oneMove) )        { bet++ ;   } 
  else if ( 0 == strcmp ("is all in with", oneMove)) { allin++ ; } 
  else                                               {           } ;
}

Step 
split (char* arr) 
{
  Step x = malloc (sizeof (keyValue)) ; 

  x->nick = strtok (arr,  "|") ;
  x->move = strtok (NULL, "|") ;

  return x ;
} ;

/*  the first  arg - name of plain nick|action file  
 *  the second arg - name of plain output file       */
int 
main (int argc, char **argv)
{
  TCMDB *hdb;
  FILE  *fd1, *fd2 ;

  hdb = tcmdbnew () ;
  fd1 = fopen (argv[1], "r") ; 

  char *buffer = malloc (1024) ;

  while ( fgets (buffer, 1024, fd1) ) 
  { 
    Step player = split (buffer) ;
    tcmdbputcat2 (hdb, player->nick, player->move) ; 
  } ;

  free (buffer) ;
  fclose (fd1) ;

  fd2 = fopen (argv[2], "w") ; 
  tcmdbiterinit (hdb) ;

  char *currNick = malloc (1024) ;

  while ( currNick = tcmdbiternext2 (hdb) ) 
  {
    char *currMoves = tcmdbget2 (hdb, currNick) ;
    char *oneMove  = malloc (1024) ; 

    oneMove = strtok (currMoves, "\n") ; 
    calcMoves (oneMove) ;
    while ( oneMove = strtok (NULL, "\n") ) { calcMoves (oneMove) ; } ;
    
    float sum = fold + check + call + bet + allin ;

    if ( sum > 135 ) 
    {
      fprintf (fd2, "%-20s | %5.2f | %5.2f | %5.2f | %5.2f | %5.2f\n", currNick, \
           (float) (fold / sum), (float) (check / sum), (float) (call / sum),   \
           (float) (bet / sum),  (float) (allin / sum) ) ;
    }
    
    fold = check = call = bet = allin = 0 ;

    free (currMoves) ;
    free (oneMove)   ;
  } ;
  
  free     (currNick) ;
  fclose   (fd2)      ;
  tcmdbdel (hdb)      ;
  return    0         ;
}  

utility API

utility API is a set of routines to handle records on memory easily: extensible string, array list, hash map, and ordered tree

#include <tcutil.h> 

objects whose type is pointer to `TCXSTR' are used for extensible string. an extensible string object is created with the function `tcxstrnew' and is deleted with the function `tcxstrdel'

objects whose type is pointer to `TCLIST' are used for array list. a list object is created with the function `tclistnew' and is deleted with the function `tclistdel'

objects whose type is pointer to `TCMAP' are used for hash map. a map object is created with the function `tcmapnew' and is deleted with the function `tcmapdel'

objects whose type is pointer to `TCTREE' are used for ordered tree. a tree object is created with the function `tctreenew' and is deleted with the function `tctreedel'

TO AVOID MEMORY LEAK, IT IS IMPORTANT TO DELETE EVERY OBJECT WHEN IT IS NO LONGER IN USE

String

TCXSTR *tcxstrnew (void) ;

to create an extensible string object. the return value is the new extensible string object

TCXSTR *tcxstrnew2 (const char *str) ;

to create an extensible string object from a character string. `str' specifies the string of the initial content. the return value is the new extensible string object containing the specified string

void tcxstrdel (TCXSTR *xstr) ;

to delete an extensible string object. xstr' specifies the extensible string object

void tcxstrclear (TCXSTR *xstr) ;

to clear an extensible string object. `xstr' specifies the extensible string object. the internal buffer of the object is cleared and the size is set zero

void tcxstrcat2 (TCXSTR *xstr, const char *str) ;

to concatenate a character string to the end of an extensible string object. xstr' specifies the extensible string object. `str' specifies the string to be appended

void tcxstrprintf (TCXSTR *xstr, const char *format, ...) ;

to perform formatted output into an extensible string object. xstr' specifies the extensible string object. `format' specifies the printf-like format string. the other arguments are used according to the format string

#include <tcutil.h>
#include <stdlib.h>
#include <stdio.h>

int main (int argc, char **argv)
{
    TCXSTR *xstr;

    xstr = tcxstrnew () ;

    tcxstrcat2 (xstr, "hop") ;
    tcxstrcat2 (xstr, "step") ;
    tcxstrcat2 (xstr, "jump") ;

    printf ("%d:%s\n", tcxstrsize (xstr), (char *)tcxstrptr (xstr)) ;
 
    tcxstrdel (xstr) ;

    return 0;
}

List

TCLIST *tclistnew (void) ;

to create a list object. the return value is the new list object

void tclistclear (TCLIST *list) ;

to clear a list object. list' specifies the list object

TCLIST *tclistnew2 (int anum) ;

to create a list object with expecting the number of elements. anum' specifies the number of elements expected to be stored in the list. the return value is the new list object

TCLIST *tclistnew3 (const char *str, ...) ;

to create a list object with initial string elements. str' specifies the string of the first element. the other arguments are other elements. they should be trailed by a `NULL' argument. the return value is the new list object

void tclistdel (TCLIST *list) ;

to delete a list object. list' specifies the list object

int tclistnum (const TCLIST *list) ;

to get the number of elements of a list object

const char *tclistval2 (const TCLIST *list, int index) ;

to get the string of an element of a list object. 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'

void tclistpush2 (TCLIST *list, const char *str) ;

to add a string element at the end of a list object. list' specifies the list object. `str' specifies the string of the new element

char *tclistpop2 (TCLIST *list) ;

to remove a string element of the end of a list object. 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'

void tclistunshift2 (TCLIST *list, const char *str) ;

to add a string element at the top of a list object. list' specifies the list object. `str' specifies the string of the new element

char *tclistshift2 (TCLIST *list) ;

to remove a string element of the top of a list object. 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'

void tclistinsert2 (TCLIST *list, int index, const char *str) ;

to add a string element at the specified location of a list object. 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

char *tclistremove2 (TCLIST *list, int index) ;

to remove a string element at the specified location of a list object. 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'

void tclistover2 (TCLIST *list, int index, const char *str) ;

to overwrite a string element at the specified location of a list object. 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

void tclistsort (TCLIST *list) ;

to sort elements of a list object in lexical order. list' specifies the list object

int tclistlsearch (const TCLIST *list, const void *ptr, int size) ;

to search a list object for an element using liner search. 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

int tclistbsearch (const TCLIST *list, const void *ptr, int size) ;

to search a list object for an element using binary search. 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

#include <tcutil.h>
#include <stdlib.h>
#include <stdio.h>

int main (int argc, char **argv)
{
    TCLIST *list;
    int i;

    list = tclistnew () ;

    tclistpush2 (list, "hop") ;
    tclistpush2 (list, "step") ;
    tclistpush2 (list, "jump") ;

    for (i = 0; i < tclistnum (list) ; i++){
      printf ("%d:%s\n", i, tclistval2 (list, i)) ;
    }
 
    tclistdel (list) ;

    return 0;
}

Map

TCMAP *tcmapnew (void) ;

to create a map object. the return value is the new map object

TCMAP *tcmapnew2 (uint32_t bnum) ;

to create a map object with specifying the number of the buckets. bnum' specifies the number of the buckets. The return value is the new map object

TCMAP *tcmapnew3 (const char *str, ...) ;

to create a map object with initial string elements. str' specifies the string of the first element. The other arguments are other elements. They should be trailed by a `NULL' argument. The return value is the new map object. The key and the value of each record are situated one after the other

void tcmapdel (TCMAP *map) ;

to delete a map object. map' specifies the map object. Note that the deleted object and its derivatives can not be used anymore

void tcmapclear (TCMAP *map) ;

to clear a map object. map' specifies the map object. All records are removed

void tcmapput2 (TCMAP *map, const char *kstr, const char *vstr) ;

to store a string record into a map object. 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

bool tcmapputkeep2 (TCMAP *map, const char *kstr, const char *vstr) ;

to store a new string record into a map object. 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

void tcmapputcat2 (TCMAP *map, const char *kstr, const char *vstr) ;

to concatenate a string value at the end of the value of the existing record in a map object. 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

bool tcmapout2 (TCMAP *map, const char *kstr) ;

to remove a string record of a map object. 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

const char *tcmapget2 (const TCMAP *map, const char *kstr) ;

to retrieve a string record in a map object. 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

void tcmapiterinit (TCMAP *map) ;

to initialize the iterator of a map object. map' specifies the map object. The iterator - to access the key of every record stored in the map object

const char *tcmapiternext2 (TCMAP *map) ;

to get the next key string of the iterator of a map object. 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

uint64_t tcmaprnum (const TCMAP *map) ;

to get the number of records stored in a map object. map' specifies the map object. The return value is the number of the records stored in the map object

TCLIST *tcmapkeys (const TCMAP *map) ;

to create a list object containing all keys in a map object. 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

TCLIST *tcmapvals (const TCMAP *map) ;

to create a list object containing all values in a map object. 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

int tcmapaddint (TCMAP *map, const void *kbuf, int ksiz, int num) ;

to add an integer to a record in a map object. 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

double tcmapadddouble (TCMAP *map, const void *kbuf, int ksiz, double num) ;

to add a real number to a record in a map object. 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

#include <tcutil.h>
#include <stdlib.h>
#include <stdio.h>

int main (int argc, char **argv)
{
    TCMAP *map;
    const char *key;

    map = tcmapnew () ;
    
    tcmapput2 (map, "foo", "hop") ;
    tcmapput2 (map, "bar", "step") ;
    tcmapput2 (map, "baz", "jump") ;
    
    tcmapiterinit (map) ;

    while ( (key = tcmapiternext2 (map)) != NULL){
      printf ("%s:%s\n", key, tcmapget2 (map, key)) ;
    }
    
    tcmapdel (map) ;

    return 0;
}

Tree

TCTREE *tctreenew (void) ;

to create a tree object. the return value is the new tree object

TCTREE *tctreenew2 (TCCMP cmp, void *cmpop) ;

to create a tree object with specifying the custom comparison function. cmp' specifies the pointer to the custom comparison function. It receives five parameters. The first parameter is the pointer to the region of one key. The second parameter is the size of the region of one key. The third parameter is the pointer to the region of the other key. The fourth parameter is the size of the region of the other key. The fifth parameter is the pointer to the optional opaque object. It returns positive if the former is big, negative if the latter is big, 0 if both are equivalent. `cmpop' specifies an arbitrary pointer to be given as a parameter of the comparison function. if it is not needed, `NULL' can be specified. The return value is the new tree object. The default comparison function compares keys of two records by lexical order. The functions `tccmplexical' (dafault), `tccmpdecimal', `tccmpint32', and `tccmpint64' are built-in

void tctreeclear (TCTREE *tree) ;

to clear a tree object. tree' specifies the tree object. All records are removed

void tctreeput2 (TCTREE *tree, const char *kstr, const char *vstr) ;

to store a string record into a tree object. 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

bool tctreeout2 (TCTREE *tree, const char *kstr) ;

to remove a string record of a tree object. 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

const char *tctreeget2 (TCTREE *tree, const char *kstr) ;

to retrieve a string record in a tree object. 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

void tctreeiterinit (TCTREE *tree) ;

to initialize the iterator of a tree object. tree' specifies the tree object. The iterator - to access the key of every record stored in the tree object

const char *tctreeiternext2 (TCTREE *tree) ;

to get the next key string of the iterator of a tree object. 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

uint64_t tctreernum (const TCTREE *tree) ;

to get the number of records stored in a tree object. tree' specifies the tree object. The return value is the number of the records stored in the tree object

TCLIST *tctreekeys (const TCTREE *tree) ;

to create a list object containing all keys in a tree object. 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

TCLIST *tctreevals (const TCTREE *tree) ;

to create a list object containing all values in a tree object. 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

int tctreeaddint (TCTREE *tree, const void *kbuf, int ksiz, int num) ;

to add an integer to a record in a tree object. 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

double tctreeadddouble (TCTREE *tree, const void *kbuf, int ksiz, double num) ;

to add a real number to a record in a tree object. 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

#include <tcutil.h>
#include <stdlib.h>
#include <stdio.h>

int main (int argc, char **argv)
{
    TCTREE *tree;
    const char *key;

    tree = tctreenew () ;

    tctreeput2 (tree, "foo", "hop") ;
    tctreeput2 (tree, "bar", "step") ;
    tctreeput2 (tree, "baz", "jump") ;

    tctreeiterinit (tree) ;

    while ( (key = tctreeiternext2 (tree)) != NULL){
      printf ("%s:%s\n", key, tctreeget2 (tree, key)) ;
    }

    tctreedel (tree) ;

    return 0;
}

memory Hash Database

TCMDB *tcmdbnew (void) ;

to create an on-memory hash database object. the return value is the new on-memory hash database object. the object can be shared by plural threads because of the internal mutex

void tcmdbdel (TCMDB *mdb) ;

to delete an on-memory hash database object

void tcmdbput2 (TCMDB *mdb, const char *kstr, const char *vstr) ;

to store a string record into an 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

bool tcmdbout2 (TCMDB *mdb, const char *kstr) ;

to remove a string record of an 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

char *tcmdbget2 (TCMDB *mdb, const char *kstr) ;

to retrieve a string record in an 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

void tcmdbiterinit (TCMDB *mdb) ;

to initialize the iterator of an on-memory hash database object

char *tcmdbiternext2 (TCMDB *mdb) ;

to get the next key string of the iterator of an 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

uint64_t tcmdbrnum (TCMDB *mdb) ;

to get the number of records stored in an on-memory hash database object

int tcmdbaddint (TCMDB *mdb, const void *kbuf, int ksiz, int num) ;

to add an integer to a record in an 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

double tcmdbadddouble (TCMDB *mdb, const void *kbuf, int ksiz, double num) ;

to add a real number to a record in an 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

void tcmdbvanish (TCMDB *mdb) ;

to clear an on-memory hash database object

memory Tree Database

TCNDB *tcndbnew (void) ;

to create an on-memory tree database object. he return value is the new on-memory tree database object. the object can be shared by plural threads because of the internal mutex

TCNDB *tcndbnew2 (TCCMP cmp, void *cmpop) ;

to create an on-memory tree database object with specifying the custom comparison function. cmp' specifies the pointer to the custom comparison function. `cmpop' specifies an arbitrary pointer to be given as a parameter of the comparison function. if it is not needed, `NULL' can be specified. the return value is the new on-memory tree database object. the default comparison function compares keys of two records by lexical order. the functions `tccmplexical' (default), `tccmpdecimal', `tccmpint32', and `tccmpint64' are built-in. the object can be shared by plural threads because of the internal mutex

void tcndbdel (TCNDB *ndb) ;

to delete an on-memory tree database object

void tcndbput2 (TCNDB *ndb, const char *kstr, const char *vstr) ;

to store a string record into an 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

bool tcndbputkeep2 (TCNDB *ndb, const char *kstr, const char *vstr) ;

to store a new string record into an 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

void tcndbputcat2 (TCNDB *ndb, const char *kstr, const char *vstr) ;

to concatenate a string at the end of the existing record in an on-memory tree database. `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

bool tcndbout2 (TCNDB *ndb, const char *kstr) ;

to remove a string record of an 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

char *tcndbget2 (TCNDB *ndb, const char *kstr) ;

to retrieve a string record in an 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

int tcndbvsiz2 (TCNDB *ndb, const char *kstr) ;

to get the size of the value of a string record in an 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

void tcndbiterinit (TCNDB *ndb) ;

to initialize the iterator of an on-memory tree database object

char *tcndbiternext2 (TCNDB *ndb) ;

to get the next key string of the iterator of an 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

TCLIST *tcndbfwmkeys2 (TCNDB *ndb, const char *pstr, int max) ;

to get forward matching string keys in an on-memory tree database object. `pstr' specifies the string of the prefix. `max' specifies the maximum number of keys to be fetched. if it is negative, no limit is specified. the return value is a list object of the corresponding keys. this function does never fail. it returns an empty list even if no key corresponds. BECAUSE THE OBJECT OF THE RETURN VALUE IS CREATED WITH THE FUNCTION `TCLISTNEW', IT SHOULD BE DELETED WITH THE FUNCTION `TCLISTDEL' WHEN IT IS NO LONGER IN USE

uint64_t tcndbrnum (TCNDB *ndb) ;

to get the number of records stored in an on-memory tree database object. the return value is the number of the records stored in the database

int tcndbaddint (TCNDB *ndb, const void *kbuf, int ksiz, int num) ;

to add an integer to a record in an on-memory tree database object. `kbuf' specifies the pointer to the region of the key. `ksiz' specifies the size of the region of the key. `num' specifies the additional value. the return value is the summation value. if the corresponding record exists, the value is treated as an integer and is added to. if no record corresponds, a new record of the additional value is stored

double tcndbadddouble (TCNDB *ndb, const void *kbuf, int ksiz, double num) ;

to add a real number to a record in an on-memory tree database object. `kbuf' specifies the pointer to the region of the key. `ksiz' specifies the size of the region of the key. `num' specifies the additional value. the return value is the summation value. if the corresponding record exists, the value is treated as a real number and is added to. if no record corresponds, a new record of the additional value is stored

The Hash Database API

#include <tchdb.h>  

objects whose type is pointer to `TCHDB' are used to handle hash databases

a hash database object is created with the function `tchdbnew' and is deleted with the function `tchdbdel'. TO AVOID MEMORY LEAK, IT IS IMPORTANT TO DELETE EVERY OBJECT WHEN IT IS NO LONGER IN USE

before operations to store or retrieve records, it is necessary to open a database file and connect the hash database object to it. the function `tchdbopen' is used to open a database file and the function `tchdbclose' is used to close the database file. TO AVOID DATA MISSING OR CORRUPTION, IT IS IMPORTANT TO CLOSE EVERY DATABASE FILE WHEN IT IS NO LONGER IN USE

it is forbidden for multible database objects in a process to open the same database at the same time

TCHDB *tchdbnew (void) ;

to create a hash database object

void tchdbdel (TCHDB *hdb) ;

to delete a hash database object

const char *tchdberrmsg (int ecode) ;

to get the message string corresponding to an error code

int tchdbecode (TCHDB *hdb) ;

to get the last happened error code of a hash database object. hdb' specifies the hash database object. the following error codes are defined:

`TCESUCCESS' for success,

`TCETHREAD' for threading error,

`TCEINVALID' for invalid operation,

`TCENOFILE' for file not found,

`TCENOPERM' for no permission,

`TCEMETA' for invalid meta data,

`TCERHEAD' for invalid record header,

`TCEOPEN' for open error,

`TCECLOSE' for close error,

`TCETRUNC' for trunc error,

`TCESYNC' for sync error,

`TCESTAT' for stat error,

`TCESEEK' for seek error,

`TCEREAD' for read error,

`TCEWRITE' for write error,

`TCEMMAP' for mmap error,

`TCELOCK' for lock error,

`TCEUNLINK' for unlink error,

`TCERENAME' for rename error,

`TCEMKDIR' for mkdir error,

`TCERMDIR' for rmdir error,

`TCEKEEP' for existing record,

`TCENOREC' for no record found,

`TCEMISC' for miscellaneous error

bool tchdbsetmutex (TCHDB *hdb) ;

to set mutual exclusion control of a hash database object for threading. if successful, the return value is true, else, it is false. note that the mutual exclusion control of the database should be set before the database is opened

bool tchdbopen (TCHDB *hdb, const char *path, int omode) ;

`path' specifies the path of the database file. `omode' specifies the connection mode:

`HDBOWRITER' as a writer

`HDBOREADER' as a reader

if the mode is `HDBOWRITER', the following may be added by bitwise-or:

`HDBOCREAT' creates a new database if not exist

`HDBOTRUNC' creates a new database regardless if one exists

`HDBOTSYNC', every transaction synchronizes updated contents with the device

both of `HDBOREADER' and `HDBOWRITER' can be added to by bitwise-or:

`HDBONOLCK' opens the database file without file locking

`HDBOLCKNB', locking is performed without blocking

if successful, the return value is true, else, it is false

bool tchdbclose (TCHDB *hdb) ;

if successful, the return value is true, else, it is false. IF A WRITER OPENS A DATABASE BUT DOES NOT CLOSE IT APPROPRIATELY, THE DATABASE WILL BE BROKEN

bool tchdbput2 (TCHDB *hdb, const char *kstr, const char *vstr) ;

to store a string record into a 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, it is overwritten

bool tchdbputkeep2 (TCHDB *hdb, const char *kstr, const char *vstr) ;

`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

bool tchdbputcat2 (TCHDB *hdb, const char *kstr, const char *vstr) ;

to concatenate a string value at the end of the existing record in a 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 there is no corresponding record, a new record is created

bool tchdbputasync2 (TCHDB *hdb, const char *kstr, const char *vstr) ;

to store a string record into a hash database object in asynchronous fashion. `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, it is overwritten. records passed to this function are accumulated into the inner buffer and wrote into the file at a blast

bool tchdbout2 (TCHDB *hdb, const char *kstr) ;

to remove a string record of a hash database object. `kstr' specifies the string of the key. if successful, the return value is true, else, it is false

char *tchdbget2 (TCHDB *hdb, const char *kstr) ;

to retrieve a string record in a 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 if 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

int tchdbvsiz2 (TCHDB *hdb, const char *kstr) ;

to get the size of the value of a string record in a 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

bool tchdbiterinit (TCHDB *hdb) ;

to initialize the iterator of a hash database object. if successful, the return value is true, else, it is false. THE ITERATOR - TO ACCESS THE KEY OF EVERY RECORD STORED IN A DATABASE

char *tchdbiternext2 (TCHDB *hdb) ;

to get the next key string of the iterator of a hash database object. if successful, the return value is the string of the next key, else, it is `NULL'. `NULL' is returned when no record is to be get out of 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

TCLIST *tchdbfwmkeys2 (TCHDB *hdb, const char *pstr, int max) ;

to get forward matching string keys in a hash database object. `pstr' specifies the string of the prefix. `max' specifies the maximum number of keys to be fetched. if it is negative, no limit is specified. the return value is a list object of the corresponding keys. this function does never fail. it returns an empty list even if no key corresponds. BECAUSE THE OBJECT OF THE RETURN VALUE IS CREATED WITH THE FUNCTION `TCLISTNEW', IT SHOULD BE DELETED WITH THE FUNCTION `TCLISTDEL' WHEN IT IS NO LONGER IN USE

int tchdbaddint (TCHDB *hdb, const void *kbuf, int ksiz, int num) ;

to add an integer to a record in a 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. if successful, the return value is the summation value, else, it is `INT_MIN'. 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

double tchdbadddouble (TCHDB *hdb, const void *kbuf, int ksiz, double num) ;

to add a real number to a record in a 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. if successful, the return value is the summation value, else, it is NaN. 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

bool tchdbtranbegin (TCHDB *hdb) ;

to begin the transaction of a hash database object. if successful, the return value is true, else, it is false. the database is locked by the thread while the transaction so that only one transaction can be activated with a database object at the same time. thus, the serializable isolation level is assumed if every database operation is performed in the transaction. all updated regions are kept track of by write ahead logging while the transaction. if the database is closed during transaction, the transaction is aborted implicitly

bool tchdbtrancommit (TCHDB *hdb) ;

to commit the transaction of a hash database object. if successful, the return value is true, else, it is false. update in the transaction is fixed when it is committed successfully

bool tchdbtranabort (TCHDB *hdb) ;

to abort the transaction of a hash database object. if successful, the return value is true, else, it is false. update in the transaction is discarded when it is aborted. the state of the database is rollbacked to before transaction

uint64_t tchdbrnum (TCHDB *hdb) ;

to get the number of records of a hash database object. the return value is the number of records or 0 if the object does not connect to any database file

#include <tchdb.h>
#include <stdlib.h>

int 
main (int argc, char **argv)
{
  TCHDB *hdb;
  int ecode;
  char *key, *value;

  hdb = tchdbnew () ;

  if (!tchdbopen (hdb, "casket.tch", HDBOWRITER | HDBOCREAT)){
    ecode = tchdbecode (hdb) ;
    fprintf (stderr, "open error: %s\n", tchdberrmsg (ecode)) ;
  }

  if (!tchdbput2 (hdb, "foo", "hop") ||
     !tchdbput2 (hdb, "bar", "step") ||
     !tchdbput2 (hdb, "baz", "jump")){
    ecode = tchdbecode (hdb) ;
    fprintf (stderr, "put error: %s\n", tchdberrmsg (ecode)) ;
  }

  value = tchdbget2 (hdb, "foo") ;
  if (value)
  {
    printf ("%s\n", value) ;
    free (value) ;
  } 
  else 
  {
    ecode = tchdbecode (hdb) ;
    fprintf (stderr, "get error: %s\n", tchdberrmsg (ecode)) ;
  }

  tchdbiterinit (hdb) ;
  while ( (key = tchdbiternext2 (hdb)) != NULL )
  {
    value = tchdbget2 (hdb, key) ;
    if (value)
    {
      printf ("%s:%s\n", key, value) ;
      free (value) ;
    }
    free (key) ;
  }

  if (!tchdbclose (hdb))
  {
    ecode = tchdbecode (hdb) ;
    fprintf (stderr, "close error: %s\n", tchdberrmsg (ecode)) ;
  }

  tchdbdel (hdb) ;

  return 0;
}

The B+ Tree Database API

#include <tcbdb.h>

objects whose type is pointer to `TCBDB' are used to handle B+ tree databases. a B+ tree database object is created with the function `tcbdbnew' and is deleted with the function `tcbdbdel'. TO AVOID MEMORY LEAK, IT IS IMPORTANT TO DELETE EVERY OBJECT WHEN IT IS NO LONGER IN USE

before operations to store or retrieve records, it is necessary to open a database file and connect the B+ tree database object to it. the function `tcbdbopen' is used to open a database file and the function `tcbdbclose' is used to close the database file. TO AVOID DATA MISSING OR CORRUPTION, IT IS IMPORTANT TO CLOSE EVERY DATABASE FILE WHEN IT IS NO LONGER IN USE

it is forbidden for multible database objects in a process to open the same database at the same time

TCBDB *tcbdbnew (void) ;

to create a B+ tree database object. he return value is the new B+ tree database object

void tcbdbdel (TCBDB *bdb) ;

to delete a B+ tree database object

const char *tcbdberrmsg (int ecode) ;

to get the message string corresponding to an error code. ecode' specifies the error code. the return value is the message string of the error code

int tcbdbecode (TCBDB *bdb) ;

to get the last happened error code of a B+ tree database object. the return value is the last happened error code. the following error codes are defined:

`TCESUCCESS' for success

`TCETHREAD' for threading error

`TCEINVALID' for invalid operation

`TCENOFILE' for file not found

`TCENOPERM' for no permission

`TCEMETA' for invalid meta data

`TCERHEAD' for invalid record header

`TCEOPEN' for open error

`TCECLOSE' for close error

`TCETRUNC' for trunc error

`TCESYNC' for sync error

`TCESTAT' for stat error

`TCESEEK' for seek error

`TCEREAD' for read error

`TCEWRITE' for write error

`TCEMMAP' for mmap error

`TCELOCK' for lock error

`TCEUNLINK' for unlink error

`TCERENAME' for rename error

`TCEMKDIR' for mkdir error

`TCERMDIR' for rmdir error

`TCEKEEP' for existing record

`TCENOREC' for no record found

and

`TCEMISC' for miscellaneous error

bool tcbdbsetmutex (TCBDB *bdb) ;

to set mutual exclusion control of a B+ tree database object for threading. bdb' specifies the B+ tree database object which is not opened. if successful, the return value is true, else, it is false. note that the mutual exclusion control of the database should be set before the database is opened

bool tcbdbsetcmpfunc (TCBDB *bdb, TCCMP cmp, void *cmpop) ;

to set the custom comparison function of a B+ tree database object. bdb' specifies the B+ tree database object which is not opened. `cmp' specifies the pointer to the custom comparison function. it receives five parameters:
the first parameter is the pointer to the region of one key
the second parameter is the size of the region of one key
the third parameter is the pointer to the region of the other key
the fourth parameter is the size of the region of the other key
the fifth parameter is the pointer to the optional opaque object
it returns positive if the former is big, negative if the latter is big, 0 if both are equivalent
`cmpop' specifies an arbitrary pointer to be given as a parameter of the comparison function. if it is not needed, `NULL' can be specified
if successful, the return value is true, else, it is false
the default comparison function compares keys of two records by lexical order. the functions `tccmplexical' (default), `tccmpdecimal', `tccmpint32', and `tccmpint64' are built-in. note that the comparison function should be set before the database is opened. moreover, user-defined comparison functions should be set every time the database is being opened

bool tcbdbopen (TCBDB *bdb, const char *path, int omode) ;

to open a database file and connect a B+ tree database object. bdb' specifies the B+ tree database object which is not opened. `path' specifies the path of the database file. `omode' specifies the connection mode: `BDBOWRITER' as a writer, `BDBOREADER' as a reader. if the mode is `BDBOWRITER', the following may be added by bitwise-or: `BDBOCREAT', which means it creates a new database if not exist, `BDBOTRUNC', which means it creates a new database regardless if one exists, `BDBOTSYNC', which means every transaction synchronizes updated contents with the device. Both of `BDBOREADER' and `BDBOWRITER' can be added to by bitwise-or: `BDBONOLCK', which means it opens the database file without file locking, or `BDBOLCKNB', which means locking is performed without blocking. if successful, the return value is true, else, it is false

bool tcbdbclose (TCBDB *bdb) ;

to close a B+ tree database object. if successful, the return value is true, else, it is false. Update of a database is assured to be written when the database is closed. if a writer opens a database but does not close it appropriately, the database will be broken

bool tcbdbput2 (TCBDB *bdb, const char *kstr, const char *vstr) ;

to store a string record into a B+ 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, it is overwritten

bool tcbdbputkeep2 (TCBDB *bdb, const char *kstr, const char *vstr) ;

to store a new string record into a B+ 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

bool tcbdbputcat2 (TCBDB *bdb, const char *kstr, const char *vstr) ;

to concatenate a string value at the end of the existing record in a B+ 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 there is no corresponding record, a new record is created

bool tcbdbout2 (TCBDB *bdb, const char *kstr) ;

to remove a string record of a B+ tree database object. `kstr' specifies the string of the key. if successful, the return value is true, else, it is false. if the key of duplicated records is specified, the first one is selected

char *tcbdbget2 (TCBDB *bdb, const char *kstr) ;

to retrieve a string record in a B+ 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 if no record corresponds. if the key of duplicated records is specified, the first one is selected. 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

int tcbdbvnum2 (TCBDB *bdb, const char *kstr) ;

to get the number of records corresponding a string key in a B+ tree database object. `kstr' specifies the string of the key. if successful, the return value is the number of the corresponding records, else, it is 0

TCLIST *tcbdbrange2 (TCBDB *bdb, const char *bkstr, bool binc, const char *ekstr, bool einc, int max) ;

to get string keys of ranged records in a B+ tree database object. `bkstr' specifies the string of the key of the beginning border. if it is `NULL', the first record is specified. `binc' specifies whether the beginning border is inclusive or not. `ekstr' specifies the string of the key of the ending border. if it is `NULL', the last record is specified. `einc' specifies whether the ending border is inclusive or not. `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 keys of the corresponding records. this function does never fail. it returns an empty list even if no record 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

TCLIST *tcbdbfwmkeys2 (TCBDB *bdb, const char *pstr, int max) ;

to get forward matching string keys in a B+ tree database object. `pstr' specifies the string of the prefix. `max' specifies the maximum number of keys to be fetched. if it is negative, no limit is specified. the return value is a list object of the corresponding keys. this function does never fail. it returns an empty list even if no key corresponds. BECAUSE THE OBJECT OF THE RETURN VALUE IS CREATED WITH THE FUNCTION `TCLISTNEW', IT SHOULD BE DELETED WITH THE FUNCTION `TCLISTDEL' WHEN IT IS NO LONGER IN USE

int tcbdbaddint (TCBDB *bdb, const void *kbuf, int ksiz, int num) ;

to add an integer to a record in a B+ tree database object. `kbuf' specifies the pointer to the region of the key. `ksiz' specifies the size of the region of the key. `num' specifies the additional value. if successful, the return value is the summation value, else, it is `INT_MIN'. 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

double tcbdbadddouble (TCBDB *bdb, const void *kbuf, int ksiz, double num) ;

to add a real number to a record in a B+ tree database object. `kbuf' specifies the pointer to the region of the key. `ksiz' specifies the size of the region of the key. `num' specifies the additional value. if successful, the return value is the summation value, else, it is Not-a-Number. 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

bool tcbdbtranbegin (TCBDB *bdb) ;

to begin the transaction of a B+ tree database object. if successful, the return value is true, else, it is false. the database is locked by the thread while the transaction so that only one transaction can be activated with a database object at the same time. thus, the serializable isolation level is assumed if every database operation is performed in the transaction. because all pages are cached on memory while the transaction, the amount of referred records is limited by the memory capacity. if the database is closed during transaction, the transaction is aborted implicitly

bool tcbdbtrancommit (TCBDB *bdb) ;

to commit the transaction of a B+ tree database object. if successful, the return value is true, else, it is false. Update in the transaction is fixed when it is committed successfully

bool tcbdbtranabort (TCBDB *bdb) ;

to abort the transaction of a B+ tree database object. if successful, the return value is true, else, it is false. Update in the transaction is discarded when it is aborted. the state of the database is rollbacked to before transaction

uint64_t tcbdbrnum (TCBDB *bdb) ;

to get the number of records of a B+ tree database object. the return value is the number of records or 0 if the object does not connect to any database file

BDBCUR *tcbdbcurnew (TCBDB *bdb) ;

to create a cursor object. the return value is the new cursor object. note that the cursor is available only after initialization with the `tcbdbcurfirst' or the `tcbdbcurjump' functions and so on. Moreover, the position of the cursor will be indefinite when the database is updated after the initialization of the cursor

void tcbdbcurdel (BDBCUR *cur) ;

to delete a cursor object. cur' specifies the cursor object

bool tcbdbcurfirst (BDBCUR *cur) ;

to move a cursor object to the first record. cur' specifies the cursor object. if successful, the return value is true, else, it is false. false is returned if there is no record in the database

bool tcbdbcurlast (BDBCUR *cur) ;

to move a cursor object to the last record. cur' specifies the cursor object. if successful, the return value is true, else, it is false. false is returned if there is no record in the database

bool tcbdbcurjump2 (BDBCUR *cur, const char *kstr) ;

to move a cursor object to the front of records corresponding a key string. cur' specifies the cursor object. `kstr' specifies the string of the key. if successful, the return value is true, else, it is false. false is returned if there is no record corresponding the condition. the cursor is set to the first record corresponding the key or the next substitute if completely matching record does not exist

bool tcbdbcurprev (BDBCUR *cur) ;

to move a cursor object to the previous record. cur' specifies the cursor object. if successful, the return value is true, else, it is false. false is returned if there is no previous record

bool tcbdbcurnext (BDBCUR *cur) ;

to move a cursor object to the next record. cur' specifies the cursor object. if successful, the return value is true, else, it is false. false is returned if there is no next record

char *tcbdbcurkey2 (BDBCUR *cur) ;

to get the key string of the record where the cursor object is. cur' specifies the cursor object. if successful, the return value is the string of the key, else, it is `NULL'. `NULL' is returned when the cursor is at invalid position. 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

char *tcbdbcurval2 (BDBCUR *cur) ;

to get the value string of the record where the cursor object is. cur' specifies the cursor object. if successful, the return value is the string of the value, else, it is `NULL'. `NULL' is returned when the cursor is at invalid position. 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

bool tcbdbcurrec (BDBCUR *cur, TCXSTR *kxstr, TCXSTR *vxstr) ;

to get the key and the value of the record where the cursor object is. cur' specifies the cursor object. `kxstr' specifies the object into which the key is wrote down. `vxstr' specifies the object into which the value is wrote down. if successful, the return value is true, else, it is false. false is returned when the cursor is at invalid position

#include <tcbdb.h>
#include <stdlib.h>

int main (int argc, char **argv)
{
  TCBDB *bdb;
  BDBCUR *cur;
  int ecode;
  char *key, *value;

  bdb = tcbdbnew () ;

  if (!tcbdbopen (bdb, "casket.tcb", BDBOWRITER | BDBOCREAT)){
    ecode = tcbdbecode (bdb) ;
    fprintf (stderr, "open error: %s\n", tcbdberrmsg (ecode)) ;
  }

  if (!tcbdbput2 (bdb, "foo", "hop") ||
     !tcbdbput2 (bdb, "bar", "step") ||
     !tcbdbput2 (bdb, "baz", "jump")){
    ecode = tcbdbecode (bdb) ;
    fprintf (stderr, "put error: %s\n", tcbdberrmsg (ecode)) ;
  }

  value = tcbdbget2 (bdb, "foo") ;
  if (value){
    printf ("%s\n", value) ;
    free (value) ;
  } else {
    ecode = tcbdbecode (bdb) ;
    fprintf (stderr, "get error: %s\n", tcbdberrmsg (ecode)) ;
  }

  /* traverse records */
  cur = tcbdbcurnew (bdb) ;
  tcbdbcurfirst (cur) ;
  while ( (key = tcbdbcurkey2 (cur)) != NULL){
    value = tcbdbcurval2 (cur) ;
    if (value){
      printf ("%s:%s\n", key, value) ;
      free (value) ;
    }
    free (key) ;
    tcbdbcurnext (cur) ;
  }
  tcbdbcurdel (cur) ;

  if (!tcbdbclose (bdb)){
    ecode = tcbdbecode (bdb) ;
    fprintf (stderr, "close error: %s\n", tcbdberrmsg (ecode)) ;
  }

  tcbdbdel (bdb) ;

  return 0;
}