fortran-tcdb

September 9, 2020 · View on GitHub

A collection of ISO C binding interfaces to the Tokyo Cabinet key-value database for Fortran 2008. At the moment, only hash databases are supported.

The interfaces are split across several modules:

tchdb.f90: File-based hash database API.
tcmdb.f90: On-memory hash database API.
tclist.f90: Array List API.
tcmisc.f90: Miscellaneous utilities API (date & time, MD5).
tcutil.f90: Includes hack to access Tokyo Cabinet version number.

Tested with Tokyo Cabinet 1.4.48 on FreeBSD 12 with GNU Fortran 9, but should be compatible to other Unix-like operating systems and Fortran 2008 compilers.

String Arguments

In some cases, convenience routines are used to add c_null_char to string arguments automatically. Performance is therefore slightly decreased, as an additional function call is necessary. To avoid these wrappers, affected interfaces are exposed directly, with a trailing underscore in their name, but null termination must be handled manually:

! Calling the wrapper function that does null termination for us:
err = tc_hdb_put2(hdb, 'foo', 'bar')

! Calling the interface directly:
err = tc_hdb_put2_(hdb, 'foo' // c_null_char, 'bar' // c_null_char)

Build

At first, install Tokyo Cabinet. On FreeBSD, run:

# pkg install databases/tokyocabinet

Development headers may be required on Linux. Then, compile the static library libfortran-tcdb.a with:

$ make static

Make sure that PREFIX points to the correct path. Link Tokyo Cabinet with libfortran-tcdb.a and -ltokyocabinet -lz -lbz2 -lrt -lpthread -lm -lc.

Example

! example.f90
program main
    use, intrinsic :: iso_c_binding, only: c_ptr
    use :: tchdb
    implicit none
    type(c_ptr)                   :: hdb
    character(len=:), allocatable :: value
    logical                       :: err

    hdb = tc_hdb_new()
    err = tc_hdb_open(hdb, 'casket.tch', ior(HDB_OWRITER, HDB_OCREAT))
    err = tc_hdb_put2(hdb, 'foo', 'bar')

    value = tc_hdb_get2(hdb, 'foo')
    print '(2a)', 'value: ', value

    err = tc_hdb_close(hdb)
    call tc_hdb_del(hdb)
end program main

Compile and run the example with:

$ gfortran -I/usr/local/include/ -L/usr/local/lib/ -o example example.f90 libfortran-tcdb.a -ltokyocabinet
$ ./example

Further Examples

Additional examples can be found in examples/:

hdb opens a hash database and does read/write operations.
mdb creates an on-memory hash database to store strings.
list pushes strings to an array list.
tcv prints the Tokyo Cabinet version number (in case you really need this info …).

Build them with:

$ make examples

Coverage

Array List API

C Function Name	Fortran Interface Name	Bound
`tclistbsearch`	`tc_list_bsearch`	✓
`tclistclear`	`tc_list_clear`	✓
`tclistdel`	`tc_list_del`	✓
`tclistdump`	`tc_list_dump`	✓
`tclistdup`	`tc_list_dup`	✓
`tclistinsert`	`tc_list_insert`	✓
`tclistinsert2`	`tc_list_insert2`, `tc_list_insert2_`	✓
`tclistload`	`tc_list_load`	✓
`tclistlsearch`	`tc_list_lsearch`	✓
`tclistnew`	`tc_list_new`	✓
`tclistnew2`	`tc_list_new2`	✓
`tclistnew3`
`tclistnum`	`tc_list_num`	✓
`tclistover`	`tc_list_over`	✓
`tclistover2`	`tc_list_over2`, `tc_list_over2_`	✓
`tclistpop`	`tc_list_pop`	✓
`tclistpop2`	`tc_list_pop2`	✓
`tclistpush`	`tc_list_push`	✓
`tclistpush2`	`tc_list_push2`, `tc_list_push2_`	✓
`tclistremove`	`tc_list_remove`	✓
`tclistremove2`	`tc_list_remove2`, `tc_list_remove2_`	✓
`tclistshift`	`tc_list_shift`	✓
`tclistshift2`	`tc_list_shift2`, `tc_list_shift2_`	✓
`tclistsort`	`tc_list_sort`	✓
`tclistunshift`	`tc_list_unshift`	✓
`tclistunshift2`	`tc_list_unshift2`, `tc_list_unshift2_`	✓
`tclistval`	`tc_list_val`	✓
`tclistval2`	`tc_list_val2`, `tc_list_val2_`	✓

On-Memory Hash Database API

C Function Name	Fortran Interface Name	Bound
`tcmdbadddouble`	`tc_mdb_add_double`	✓
`tcmdbaddint`	`tc_mdb_add_int`	✓
`tcmdbcutfront`	`tc_mdb_cut_front`	✓
`tcmdbdel`	`tc_mdb_del`	✓
`tcmdbfwmkeys`	`tc_mdb_fwm_keys`	✓
`tcmdbfwmkeys2`	`tc_mdb_fwm_keys2`, `tc_mdb_fwm_keys2_`	✓
`tcmdbget`	`tc_mdb_get`	✓
`tcmdbget2`	`tc_mdb_get2`, `tc_mdb_get2_`	✓
`tcmdbiterinit`	`tc_mdb_iter_init`	✓
`tcmdbiternext`	`tc_mdb_iter_next`	✓
`tcmdbiternext2`	`tc_mdb_iter_next2`	✓
`tcmdbmsiz`	`tc_mdb_msiz`	✓
`tcmdbnew`	`tc_mdb_new`	✓
`tcmdbnew2`	`tc_mdb_new2`	✓
`tcmdbout`	`tc_mdb_out`	✓
`tcmdbout2`	`tc_mdb_out2`, `tc_mdb_out2_`	✓
`tcmdbput`	`tc_mdb_put`	✓
`tcmdbput2`	`tc_mdb_put2`, `tc_mdb_put2_`	✓
`tcmdbputcat`	`tc_mdb_put_cat`	✓
`tcmdbputcat2`	`tc_mdb_put_cat2`, `tc_mdb_put_cat2_`	✓
`tcmdbputkeep`	`tc_mdb_put_keep`	✓
`tcmdbputkeep2`	`tc_mdb_put_keep2`, `tc_mdb_put_keep2_`	✓
`tcmdbrnum`	`tc_mdb_rnum`	✓
`tcmdbvanish`	`tc_mdb_vanish`	✓
`tcmdbvsiz`	`tc_mdb_vsiz`	✓
`tcmdbvsiz2`	`tc_mdb_vsiz2`, `tc_mdb_vsiz2_`	✓

Hash Database API

C Function Name	Fortran Interface Name	Bound
`tchdbadddouble`	`tc_hdb_add_double`	✓
`tchdbaddint`	`tc_hdb_add_int`	✓
`tchdbclose`	`tc_hdb_close`	✓
`tchdbcopy`	`tc_hdb_copy`, `tc_hdb_copy_`	✓
`tchdbdel`	`tc_hdb_del`	✓
`tchdbecode`	`tc_hdb_ecode`	✓
`tchdberrmsg`	`tc_hdb_err_msg`	✓
`tchdbfsiz`	`tc_hdb_fsiz`	✓
`tchdbfwmkeys`	`tc_hdb_fwm_keys`	✓
`tchdbfwmkeys2`	`tc_hdb_fwm_keys2`, `tc_hdb_fwm_keys2_`	✓
`tchdbget`	`tc_hdb_get`	✓
`tchdbget2`	`tc_hdb_get2`, `tc_hdb_get2_`	✓
`tchdbget3`	`tc_hdb_get3`	✓
`tchdbiterinit`	`tc_hdb_iter_init`	✓
`tchdbiternext`	`tc_hdb_iter_next`	✓
`tchdbiternext2`	`tc_hdb_iter_next2`	✓
`tchdbiternext3`	`tc_hdb_iter_next3`	✓
`tchdbnew`	`tc_hdb_new`	✓
`tchdbopen`	`tc_hdb_open`, `tc_hdb_open_`	✓
`tchdboptimize`	`tc_hdb_optimize`	✓
`tchdbout`	`tc_hdb_out`	✓
`tchdbout2`	`tc_hdb_out2`, `tc_hdb_out2_`	✓
`tchdbpath`	`tc_hdb_path`	✓
`tchdbput`	`tc_hdb_put`	✓
`tchdbput2`	`tc_hdb_put2`, `tc_hdb_put2_`	✓
`tchdbputasync`	`tc_hdb_put_async`	✓
`tchdbputasync2`	`tc_hdb_put_async2`, `tc_hdb_put_async2_`	✓
`tchdbputcat`	`tc_hdb_put_cat`	✓
`tchdbputcat2`	`tc_hdb_put_cat2`, `tc_hdb_put_cat2_`	✓
`tchdbputkeep`	`tc_hdb_put_keep`	✓
`tchdbputkeep2`	`tc_hdb_put_keep2`, `tc_hdb_put_keep2_`	✓
`tchdbrnum`	`tc_hdb_rnum`	✓
`tchdbsetdfunit`	`tc_hdb_set_dfunit`	✓
`tchdbsetcache`	`tc_hdb_set_cache`	✓
`tchdbsetmutex`	`tc_hdb_set_mutex`	✓
`tchdbsetxmsiz`	`tc_hdb_set_xmsiz`	✓
`tchdbsync`	`tc_hdb_sync`	✓
`tchdbtranabort`	`tc_hdb_tran_abort`	✓
`tchdbtranbegin`	`tc_hdb_tran_begin`	✓
`tchdbtrancommit`	`tc_hdb_tran_commit`	✓
`tchdbtune`	`tc_hdb_tune`	✓
`tchdbvanish`	`tc_hdb_vanish`	✓
`tchdbvsiz`	`tc_hdb_vsiz`	✓
`tchdbvsiz2`	`tc_hdb_vsiz2`, `tc_hdb_vsiz2_`	✓

Basic Utilities API

C Variable Name	Fortran Interface Name	Bound
`*tcversion`	`tc_version`	✓

Miscellaneous Utilities API

C Function Name	Fortran Interface Name	Bound
`tcdatestrwww`	`tc_date_str_www`	✓
`tcmd5hash`	`tc_md5_hash`	✓
`tcstrmktime`	`tc_str_mk_time`	✓

Licence

ISC