Module tokyocabinet

The Lua binding of Tokyo Cabinet.

Functions

adb:adddouble (key, num) Add a real number to a record.
adb:addint (key, num) Add an integer to a record.
adb:close () Close the database.
adb:copy (path) Copy the database file.
adb:foreach (func) Process each record atomically.
adb:fwmkeys (prefix, max) Get forward matching keys.
adb:get (key) Retrieve a record.
adb:iterinit () Initialize the iterator.
adb:iternext () Get the next key of the iterator.
adb:open (name) Open a database.
adb:optimize (params) Optimize the storage.
adb:out (key) Remove a record.
adb:pairs () Get the iterator for generic "for" loop.
adb:path () Get the path of the database file.
adb:put (key, value) Store a record.
adb:putcat (key, value) Concatenate a value at the end of the existing record.
adb:putkeep (key, value) Store a new record.
adb:rnum () Get the number of records.
adb:size () Get the size of the database.
adb:sync () Synchronize updated contents with the file and the device.
adb:tranabort () Abort the transaction.
adb:tranbegin () Begin the transaction.
adb:trancommit () Commit the transaction.
adb:vanish () Remove all records.
adb:vsiz (key) Get the size of the value of a record.
bdb:adddouble (key, num) Add a real number to a record.
bdb:addint (key, num) Add an integer to a record.
bdb:close () Close the database file.
bdb:copy (path) Copy the database file.
bdb:ecode () Get the last happened error code.
bdb:errmsg (ecode) Get the message string corresponding to an error code.
bdb:foreach (func) Process each record atomically.
bdb:fsiz () Get the size of the database file.
bdb:fwmkeys (prefix, max) Get forward matching keys.
bdb:get (key) Retrieve a record.
bdb:getlist (key) Retrieve records.
bdb:open (path, omode) Open a database file.
bdb:optimize (lmemb, nmemb, bnum, apow, fpow, opts) Optimize the database file.
bdb:out (key) Remove a record.
bdb:outlist (key) Remove records.
bdb:pairs () Get the iterator for generic "for" loop.
bdb:path () Get the path of the database file.
bdb:put (key, value) Store a record.
bdb:putcat (key, value) Concatenate a value at the end of the existing record.
bdb:putdup (key, value) Store a record with allowing duplication of keys.
bdb:putkeep (key, value) Store a new record.
bdb:putlist (key, values) Store records with allowing duplication of keys.
bdb:range (bkey, binc, ekey, einc, max) Get keys of ranged records.
bdb:rnum () Get the number of records.
bdb:setcache (lcnum, ncnum) Set the caching parameters.
bdb:setcmpfunc (cmp) Set the custom comparison function.
bdb:setdfunit (dfunit) Set the unit step number of auto defragmentation.
bdb:setxmsiz (xmsiz) Set the size of the extra mapped memory.
bdb:sync () Synchronize updated contents with the file and the device.
bdb:tranabort () Abort the transaction.
bdb:tranbegin () Begin the transaction.
bdb:trancommit () Commit the transaction.
bdb:tune (lmemb, nmemb, bnum, apow, fpow, opts) Set the tuning parameters.
bdb:vanish () Remove all records.
bdb:vnum (key) Get the number of records corresponding a key.
bdb:vsiz (key) Get the size of the value of a record.
bdbcur:first () Move the cursor to the first record.
bdbcur:jump (key) Move the cursor to the front of records corresponding a key.
bdbcur:key () Get the key of the record where the cursor is.
bdbcur:last () Move the cursor to the last record.
bdbcur:next () Move the cursor to the next record.
bdbcur:out () Remove the record where the cursor is.
bdbcur:prev () Move the cursor to the previous record.
bdbcur:put (value, cpmode) Insert a record around the cursor.
bdbcur:val () Get the value of the record where the cursor is.
fdb:adddouble (key, num) Add a real number to a record.
fdb:addint (key, num) Add an integer to a record.
fdb:close () Close the database file.
fdb:copy (path) Copy the database file.
fdb:ecode () Get the last happened error code.
fdb:errmsg (ecode) Get the message string corresponding to an error code.
fdb:foreach (func) Process each record atomically.
fdb:fsiz () Get the size of the database file.
fdb:get (key) Retrieve a record.
fdb:iterinit () Initialize the iterator.
fdb:iternext () Get the next key of the iterator.
fdb:open (path, omode) Open a database file.
fdb:optimize (width, limsiz) Optimize the database file.
fdb:out (key) Remove a record.
fdb:pairs () Get the iterator for generic "for" loop.
fdb:path () Get the path of the database file.
fdb:put (key, value) Store a record.
fdb:putcat (key, value) Concatenate a value at the end of the existing record.
fdb:putkeep (key, value) Store a new record.
fdb:range (interval, max) Get keys with an interval notation.
fdb:rnum () Get the number of records.
fdb:sync () Synchronize updated contents with the file and the device.
fdb:tranabort () Abort the transaction.
fdb:tranbegin () Begin the transaction.
fdb:trancommit () Commit the transaction.
fdb:tune (width, limsiz) Set the tuning parameters.
fdb:vanish () Remove all records.
fdb:vsiz (key) Get the size of the value of a record.
hdb:adddouble (key, num) Add a real number to a record.
hdb:addint (key, num) Add an integer to a record.
hdb:close () Close the database file.
hdb:copy (path) Copy the database file.
hdb:ecode () Get the last happened error code.
hdb:errmsg (ecode) Get the message string corresponding to an error code.
hdb:foreach (func) Process each record atomically.
hdb:fsiz () Get the size of the database file.
hdb:fwmkeys (prefix, max) Get forward matching keys.
hdb:get (key) Retrieve a record.
hdb:iterinit () Initialize the iterator.
hdb:iternext () Get the next key of the iterator.
hdb:open (path, omode) Open a database file.
hdb:optimize (bnum, apow, fpow, opts) Optimize the database file.
hdb:out (key) Remove a record.
hdb:pairs () Get the iterator for generic "for" loop.
hdb:path () Get the path of the database file.
hdb:put (key, value) Store a record.
hdb:putasync (key, value) Store a record in asynchronous fashion.
hdb:putcat (key, value) Concatenate a value at the end of the existing record.
hdb:putkeep (key, value) Store a new record.
hdb:rnum () Get the number of records.
hdb:setcache (rcnum) Set the caching parameters.
hdb:setdfunit (dfunit) Set the unit step number of auto defragmentation.
hdb:setxmsiz (xmsiz) Set the size of the extra mapped memory.
hdb:sync () Synchronize updated contents with the file and the device.
hdb:tranabort () Abort the transaction.
hdb:tranbegin () Begin the transaction.
hdb:trancommit () Commit the transaction.
hdb:tune (bnum, apow, fpow, opts) Set the tuning parameters.
hdb:vanish () Remove all records.
hdb:vsiz (key) Get the size of the value of a record.
tdb:adddouble (pkey, num) Add a real number to a record.
tdb:addint (pkey, num) Add an integer to a record.
tdb:close () Close the database file.
tdb:copy (path) Copy the database file.
tdb:ecode () Get the last happened error code.
tdb:errmsg (ecode) Get the message string corresponding to an error code.
tdb:foreach (func) Process each record atomically.
tdb:fsiz () Get the size of the database file.
tdb:fwmkeys (prefix, max) Get forward matching primary keys.
tdb:genuid () Generate a unique ID number.
tdb:get (pkey) Retrieve a record.
tdb:iterinit () Initialize the iterator.
tdb:iternext () Get the next primary key of the iterator.
tdb:open (path, omode) Open a database file.
tdb:optimize (bnum, apow, fpow, opts) Optimize the database file.
tdb:out (pkey) Remove a record.
tdb:pairs () Get the iterator for generic "for" loop.
tdb:path () Get the path of the database file.
tdb:put (pkey, cols) Store a record.
tdb:putcat (pkey, cols) Concatenate columns of the existing record.
tdb:putkeep (pkey, cols) Store a new record.
tdb:rnum () Get the number of records.
tdb:setcache (rcnum, lcnum, ncnum) Set the caching parameters.
tdb:setdfunit (dfunit) Set the unit step number of auto defragmentation.
tdb:setindex (name, type) Set a column index.
tdb:setxmsiz (xmsiz) Set the size of the extra mapped memory.
tdb:sync () Synchronize updated contents with the file and the device.
tdb:tranabort () Abort the transaction.
tdb:tranbegin () Begin the transaction.
tdb:trancommit () Commit the transaction.
tdb:tune (bnum, apow, fpow, opts) Set the tuning parameters.
tdb:vanish () Remove all records.
tdb:vsiz (pkey) Get the size of the value of a record.
tdbqry:addcond (name, op, expr) Add a narrowing condition.
tdbqry:hint () Get the hint string.
tdbqry:kwic (cols, name, width, opts) Generate keyword-in-context strings.
tdbqry:metasearch (others, type) Retrieve records with multiple query objects and get the set of the result.
tdbqry:proc () Process each corresponding record.
tdbqry:search () Execute the search.
tdbqry:searchout () Remove each corresponding record.
tdbqry:setlimit (max, skip) Set the maximum number of records of the result.
tdbqry:setorder (name, type) Set the order of the result.
tokyocabinet.adbnew () Create an abstract database object.
tokyocabinet.bdbcurnew (bdb) Create a cursor object of a B+ tree database object.
tokyocabinet.bdbnew () Create a B+ tree database object.
tokyocabinet.bit (mode, num, aux) Perform bit operation of an integer.
tokyocabinet.chdir (path) Change the current working directory.
tokyocabinet.codec (mode, str) Encode or decode a string.
tokyocabinet.dist (astr, bstr, isutf) Calculate the edit distance of two UTF-8 strings.
tokyocabinet.fdbnew () Create a fixed-length database object.
tokyocabinet.glob (pattern) Find pathnames matching a pattern.
tokyocabinet.hash (mode, str) Get the hash value of a string.
tokyocabinet.hdbnew () Create a hash database object.
tokyocabinet.isect (ary, ...) Calculate the intersection set of arrays.
tokyocabinet.mkdir (path) Create a directory.
tokyocabinet.pack (format, ary, ...) Serialize an array of numbers into a string.
tokyocabinet.regex (str, pattern, alt) Perform pattern matching or replacement with regular expressions.
tokyocabinet.remove (path) Remove a file or a directory and its sub ones recursively.
tokyocabinet.sleep (sec) Suspend execution for the specified interval.
tokyocabinet.split (str, delims) Split a string into substrings.
tokyocabinet.stat (path) Get the status of a file.
tokyocabinet.strstr (str, pattern, alt) Perform substring matching or replacement without evaluating any meta character.
tokyocabinet.tablenew (anum, rnum) Create a table with specifying the number of array elements and the number of hash records.
tokyocabinet.tdbnew () Create a table database object.
tokyocabinet.tdbqrynew (tdb) Create a query object of a table database object.
tokyocabinet.time () Get the time of day in seconds.
tokyocabinet.ucs (data) Convert a UTF-8 string into a UCS-2 array or its inverse.
tokyocabinet.union (ary, ...) Calculate the union set of arrays.
tokyocabinet.unpack (format, str) Deserialize a binary string into an array of numbers.


Functions

adb:adddouble (key, num)
Add a real number to a record. 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.

Parameters

  • key: the key.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
adb:addint (key, num)
Add an integer to a record. 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.

Parameters

  • key: the key.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
adb:close ()
Close the database. 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.

Return value:

If successful, it is true, else, it is false.
adb:copy (path)
Copy the database file. The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress. So, this method is useful to create a backup file of the database file.

Parameters

  • path: the path of the destination file. If it begins with `@', the trailing substring is executed as a command line.

Return value:

If successful, it is true, else, it is false. False is returned if the executed command returns non-zero code.
adb:foreach (func)
Process each record atomically.

Parameters

  • func: the iterator function called for each record. It receives two parameters of the key and the value, and returns true to continue iteration or false to stop iteration.

Return value:

If successful, it is true, else, it is false.
adb:fwmkeys (prefix, max)
Get forward matching keys. This function may be very slow because every key in the database is scanned.

Parameters

  • prefix: the prefix of the corresponding keys.
  • max: the maximum number of keys to be fetched. If it is negative, no limit is specified.

Return value:

an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
adb:get (key)
Retrieve a record.

Parameters

  • key: the key.

Return value:

If successful, it is the value of the corresponding record. `nil' is returned if no record corresponds.
adb:iterinit ()
Initialize the iterator. The iterator is used in order to access the key of every record stored in a database.

Return value:

If successful, it is true, else, it is false.
adb:iternext ()
Get the next key of the iterator. It is possible to access every record by iteration of calling this method. It is allowed to update or remove records whose keys are fetched while the iteration. However, it is not assured if updating the database is occurred while the iteration. Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.

Return value:

If successful, it is the next key, else, it is `nil'. `nil' is returned when no record is to be get out of the iterator.
adb:open (name)
Open a database.

Parameters

  • name: the name of the database. If it is "*", the database will be an on-memory hash database. If it is "+", the database will be an on-memory tree database. If its suffix is ".tch", the database will be a hash database. If its suffix is ".tcb", the database will be a B+ tree database. If its suffix is ".tcf", the database will be a fixed-length database. If its suffix is ".tct", the database will be a table database. Otherwise, this method fails. Tuning parameters can trail the name, separated by "#". Each parameter is composed of the name and the value, separated by "=". On-memory hash database supports "bnum", "capnum", and "capsiz". On-memory tree database supports "capnum" and "capsiz". Hash database supports "mode", "bnum", "apow", "fpow", "opts", "rcnum", and "xmsiz". B+ tree database supports "mode", "lmemb", "nmemb", "bnum", "apow", "fpow", "opts", "lcnum", "ncnum", and "xmsiz". Fixed-length database supports "mode", "width", and "limsiz". Table database supports "mode", "bnum", "apow", "fpow", "opts", "rcnum", "lcnum", "ncnum", "xmsiz", and "idx". The tuning parameter "capnum" specifies the capacity number of records. "capsiz" specifies the capacity size of using memory. Records spilled the capacity are removed by the storing order. "mode" can contain "w" of writer, "r" of reader, "c" of creating, "t" of truncating, "e" of no locking, and "f" of non-blocking lock. The default mode is relevant to "wc". "opts" can contains "l" of large option, "d" of Deflate option, "b" of BZIP2 option, and "t" of TCBS option. "idx" specifies the column name of an index and its type separated by ":". For example, "casket.tch#bnum=1000000#opts=ld" means that the name of the database file is "casket.tch", and the bucket number is 1000000, and the options are large and Deflate.

Return value:

If successful, it is true, else, it is false.
adb:optimize (params)
Optimize the storage.

Parameters

  • params: the string of the tuning parameters, which works as with the tuning of parameters the method `open'. If it is not defined, it is not used.

Return value:

If successful, it is true, else, it is false.
adb:out (key)
Remove a record.

Parameters

  • key: the key.

Return value:

If successful, it is true, else, it is false.
adb:pairs ()
Get the iterator for generic "for" loop.

Return value:

plural values; the iterator to retrieve the key and the value of the next record, the table itself, and nil.
adb:path ()
Get the path of the database file.

Return value:

the path of the database file or `nil' if the object does not connect to any database file. "*" stands for on-memory hash database. "+" stands for on-memory tree database.
adb:put (key, value)
Store a record. If a record with the same key exists in the database, it is overwritten.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
adb:putcat (key, value)
Concatenate a value at the end of the existing record. If there is no corresponding record, a new record is created.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
adb:putkeep (key, value)
Store a new record. If a record with the same key exists in the database, this method has no effect.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
adb:rnum ()
Get the number of records.

Return value:

the number of records or 0 if the object does not connect to any database file.
adb:size ()
Get the size of the database.

Return value:

the size of the database file or 0 if the object does not connect to any database file.
adb:sync ()
Synchronize updated contents with the file and the device. This method is useful when another process connects the same database file.

Return value:

If successful, it is true, else, it is false.
adb:tranabort ()
Abort the transaction. Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction.

Return value:

If successful, it is true, else, it is false.
adb:tranbegin ()
Begin the transaction. 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.

Return value:

If successful, it is true, else, it is false.
adb:trancommit ()
Commit the transaction. Update in the transaction is fixed when it is committed successfully.

Return value:

If successful, it is true, else, it is false.
adb:vanish ()
Remove all records.

Return value:

If successful, it is true, else, it is false.
adb:vsiz (key)
Get the size of the value of a record.

Parameters

  • key: the key.

Return value:

If successful, it is the size of the value of the corresponding record, else, it is -1.
bdb:adddouble (key, num)
Add a real number to a record. 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.

Parameters

  • key: the key.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
bdb:addint (key, num)
Add an integer to a record. 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.

Parameters

  • key: the key.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
bdb:close ()
Close the database file. 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.

Return value:

If successful, it is true, else, it is false.
bdb:copy (path)
Copy the database file. The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress. So, this method is useful to create a backup file of the database file.

Parameters

  • path: the path of the destination file. If it begins with `@', the trailing substring is executed as a command line.

Return value:

If successful, it is true, else, it is false. False is returned if the executed command returns non-zero code.
bdb:ecode ()
Get the last happened error code.

Return value:

the last happened error code. The following error codes are defined: `bdb.ESUCCESS' for success, `bdb.ETHREAD' for threading error, `bdb.EINVALID' for invalid operation, `bdb.ENOFILE' for file not found, `bdb.ENOPERM' for no permission, `bdb.EMETA' for invalid meta data, `bdb.ERHEAD' for invalid record header, `bdb.EOPEN' for open error, `bdb.ECLOSE' for close error, `bdb.ETRUNC' for trunc error, `bdb.ESYNC' for sync error, `bdb.ESTAT' for stat error, `bdb.ESEEK' for seek error, `bdb.EREAD' for read error, `bdb.EWRITE' for write error, `bdb.EMMAP' for mmap error, `bdb.ELOCK' for lock error, `bdb.EUNLINK' for unlink error, `bdb.ERENAME' for rename error, `bdb.EMKDIR' for mkdir error, `bdb.ERMDIR' for rmdir error, `bdb.EKEEP' for existing record, `bdb.ENOREC' for no record found, and `bdb.EMISC' for miscellaneous error.
bdb:errmsg (ecode)
Get the message string corresponding to an error code.

Parameters

  • ecode: the error code. If it is not defined or negative, the last happened error code is specified.

Return value:

the message string of the error code.
bdb:foreach (func)
Process each record atomically.

Parameters

  • func: the iterator function called for each record. It receives two parameters of the key and the value, and returns true to continue iteration or false to stop iteration.

Return value:

If successful, it is true, else, it is false.
bdb:fsiz ()
Get the size of the database file.

Return value:

the size of the database file or 0 if the object does not connect to any database file.
bdb:fwmkeys (prefix, max)
Get forward matching keys.

Parameters

  • prefix: the prefix of the corresponding keys.
  • max: the maximum number of keys to be fetched. If it is not defined or negative, no limit is specified.

Return value:

an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
bdb:get (key)
Retrieve a record. If the key of duplicated records is specified, the first one is selected.

Parameters

  • key: the key.

Return value:

If successful, it is the value of the corresponding record. `nil' is returned if no record corresponds.
bdb:getlist (key)
Retrieve records.

Parameters

  • key: the key.

Return value:

If successful, it is an array of the values of the corresponding records. `nil' is returned if no record corresponds.
bdb:open (path, omode)
Open a database file.

Parameters

  • path: the path of the database file.
  • omode: the connection mode: `bdb.OWRITER' as a writer, `bdb.OREADER' as a reader. If the mode is `bdb.OWRITER', the following may be added by bitwise-or: `bdb.OCREAT', which means it creates a new database if not exist, `bdb.OTRUNC', which means it creates a new database regardless if one exists, `bdb.OTSYNC', which means every transaction synchronizes updated contents with the device. Both of `bdb.OREADER' and `bdb.OWRITER' can be added to by bitwise-or: `bdb.ONOLCK', which means it opens the database file without file locking, or `bdb.OLCKNB', which means locking is performed without blocking. If it is not defined or `bdb.OREADER' is specified.

Return value:

If successful, it is true, else, it is false.
bdb:optimize (lmemb, nmemb, bnum, apow, fpow, opts)
Optimize the database file. This method is useful to reduce the size of the database file with data fragmentation by successive updating.

Parameters

  • lmemb: the number of members in each leaf page. If it is not defined or not more than 0, the current setting is not changed.
  • nmemb: the number of members in each non-leaf page. If it is not defined or not more than 0, the current setting is not changed.
  • bnum: the number of elements of the bucket array. If it is not defined or not more than 0, the default value is specified. The default value is two times of the number of pages.
  • apow: the size of record alignment by power of 2. If it is not defined or negative, the current setting is not changed.
  • fpow: the maximum number of elements of the free block pool by power of 2. If it is not defined or negative, the current setting is not changed.
  • opts: options by bitwise-or: `bdb.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `bdb.TDEFLATE' specifies that each record is compressed with Deflate encoding, `bdb.TBZIP' specifies that each record is compressed with BZIP2 encoding, `bdb.TTCBS' specifies that each record is compressed with TCBS encoding. If it is not defined or 0xff, the current setting is not changed.

Return value:

If successful, it is true, else, it is false.
bdb:out (key)
Remove a record. If the key of duplicated records is specified, the first one is selected.

Parameters

  • key: the key.

Return value:

If successful, it is true, else, it is false.
bdb:outlist (key)
Remove records. If the key of duplicated records is specified, all of them are removed.

Parameters

  • key: the key.

Return value:

If successful, it is true, else, it is false.
bdb:pairs ()
Get the iterator for generic "for" loop.

Return value:

plural values; the iterator to retrieve the key and the value of the next record, the cursor for iteration, and nil.
bdb:path ()
Get the path of the database file.

Return value:

the path of the database file or `nil' if the object does not connect to any database file.
bdb:put (key, value)
Store a record. If a record with the same key exists in the database, it is overwritten.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
bdb:putcat (key, value)
Concatenate a value at the end of the existing record. If there is no corresponding record, a new record is created.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
bdb:putdup (key, value)
Store a record with allowing duplication of keys. If a record with the same key exists in the database, the new record is placed after the existing one.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
bdb:putkeep (key, value)
Store a new record. If a record with the same key exists in the database, this method has no effect.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
bdb:putlist (key, values)
Store records with allowing duplication of keys. If a record with the same key exists in the database, the new records are placed after the existing one.

Parameters

  • key: the key.
  • values: an array of the values.

Return value:

If successful, it is true, else, it is false.
bdb:range (bkey, binc, ekey, einc, max)
Get keys of ranged records.

Parameters

  • bkey: the key of the beginning border. If it is not defined, the first record is specified.
  • binc: whether the beginning border is inclusive or not. If it is not defined, false is specified.
  • ekey: the key of the ending border. If it is not defined, the last record is specified.
  • einc: whether the ending border is inclusive or not. If it is not defined, false is specified.
  • max: the maximum number of keys to be fetched. If it is not defined or negative, no limit is specified.

Return value:

an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
bdb:rnum ()
Get the number of records.

Return value:

the number of records or 0 if the object does not connect to any database file.
bdb:setcache (lcnum, ncnum)
Set the caching parameters. The tuning parameters of the database should be set before the database is opened.

Parameters

  • lcnum: the maximum number of leaf nodes to be cached. If it is not defined or not more than 0, the default value is specified. The default value is 1024.
  • ncnum: the maximum number of non-leaf nodes to be cached. If it is not defined or not more than 0, the default value is specified. The default value is 512.

Return value:

If successful, it is true, else, it is false.
bdb:setcmpfunc (cmp)
Set the custom comparison function. The default comparison function compares keys of two records by lexical order. The constants `bdb.CMPLEXICAL' (dafault), `bdb.CMPDECIMAL', `bdb.CMPINT32', and `bdb.CMPINT64' 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.

Parameters

  • cmp: the custom comparison function.

Return value:

If successful, it is true, else, it is false.
bdb:setdfunit (dfunit)
Set the unit step number of auto defragmentation.

Parameters

  • dfunit: the unit step number. If it is not more than 0, the auto defragmentation is disabled. It is disabled by default.

Return value:

If successful, it is true, else, it is false.
bdb:setxmsiz (xmsiz)
Set the size of the extra mapped memory. The mapping parameters should be set before the database is opened.

Parameters

  • xmsiz: the size of the extra mapped memory. If it is not defined or not more than 0, the extra mapped memory is disabled. It is disabled by default.

Return value:

If successful, it is true, else, it is false.
bdb:sync ()
Synchronize updated contents with the file and the device. This method is useful when another process connects the same database file.

Return value:

If successful, it is true, else, it is false.
bdb:tranabort ()
Abort the transaction. Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction.

Return value:

If successful, it is true, else, it is false.
bdb:tranbegin ()
Begin the transaction. 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.

Return value:

If successful, it is true, else, it is false.
bdb:trancommit ()
Commit the transaction. Update in the transaction is fixed when it is committed successfully.

Return value:

If successful, it is true, else, it is false.
bdb:tune (lmemb, nmemb, bnum, apow, fpow, opts)
Set the tuning parameters. The tuning parameters of the database should be set before the database is opened.

Parameters

  • lmemb: the number of members in each leaf page. If it is not defined or not more than 0, the default value is specified. The default value is 128.
  • nmemb: the number of members in each non-leaf page. If it is not defined or not more than 0, the default value is specified. The default value is 256.
  • bnum: the number of elements of the bucket array. If it is not defined or not more than 0, the default value is specified. The default value is 32749. Suggested size of the bucket array is about from 1 to 4 times of the number of all pages to be stored.
  • apow: the size of record alignment by power of 2. If it is not defined or negative, the default value is specified. The default value is 4 standing for 2^8=256.
  • fpow: the maximum number of elements of the free block pool by power of 2. If it is not defined or negative, the default value is specified. The default value is 10 standing for 2^10=1024.
  • opts: options by bitwise-or: `bdb.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `bdb.TDEFLATE' specifies that each record is compressed with Deflate encoding, `bdb.TBZIP' specifies that each record is compressed with BZIP2 encoding, `bdb.TTCBS' specifies that each record is compressed with TCBS encoding. If it is not defined, no option is specified.

Return value:

If successful, it is true, else, it is false.
bdb:vanish ()
Remove all records.

Return value:

If successful, it is true, else, it is false.
bdb:vnum (key)
Get the number of records corresponding a key.

Parameters

  • key: the key.

Return value:

If successful, it is the number of the corresponding records, else, it is 0.
bdb:vsiz (key)
Get the size of the value of a record. If the key of duplicated records is specified, the first one is selected.

Parameters

  • key: the key.

Return value:

If successful, it is the size of the value of the corresponding record, else, it is -1.
bdbcur:first ()
Move the cursor to the first record.

Return value:

If successful, it is true, else, it is false. False is returned if there is no record in the database.
bdbcur:jump (key)
Move the cursor to the front of records corresponding a key. The cursor is set to the first record corresponding the key or the next substitute if completely matching record does not exist.

Parameters

  • key: the key.

Return value:

If successful, it is true, else, it is false. False is returned if there is no record corresponding the condition.
bdbcur:key ()
Get the key of the record where the cursor is.

Return value:

If successful, it is the key, else, it is `null'. 'null' is returned when the cursor is at invalid position.
bdbcur:last ()
Move the cursor to the last record.

Return value:

If successful, it is true, else, it is false. False is returned if there is no record in the database.
bdbcur:next ()
Move the cursor to the next record.

Return value:

If successful, it is true, else, it is false. False is returned if there is no next record.
bdbcur:out ()
Remove the record where the cursor is. After deletion, the cursor is moved to the next record if possible.

Return value:

If successful, it is true, else, it is false. False is returned when the cursor is at invalid position.
bdbcur:prev ()
Move the cursor to the previous record.

Return value:

If successful, it is true, else, it is false. False is returned if there is no previous record.
bdbcur:put (value, cpmode)
Insert a record around the cursor. After insertion, the cursor is moved to the inserted record.

Parameters

  • value: the value.
  • cpmode: detail adjustment: `bdbcur.CPCURRENT', which means that the value of the current record is overwritten, `bdbcur.CPBEFORE', which means that the new record is inserted before the current record, `bdbcur.CPAFTER', which means that the new record is inserted after the current record.

Return value:

If successful, it is true, else, it is false. False is returned when the cursor is at invalid position.
bdbcur:val ()
Get the value of the record where the cursor is.

Return value:

If successful, it is the value, else, it is `null'. 'null' is returned when the cursor is at invalid position.
fdb:adddouble (key, num)
Add a real number to a record. 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.

Parameters

  • key: the key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
fdb:addint (key, num)
Add an integer to a record. 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.

Parameters

  • key: the key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
fdb:close ()
Close the database file. 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.

Return value:

If successful, it is true, else, it is false.
fdb:copy (path)
Copy the database file. The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress. So, this method is useful to create a backup file of the database file.

Parameters

  • path: the path of the destination file. If it begins with `@', the trailing substring is executed as a command line.

Return value:

If successful, it is true, else, it is false. False is returned if the executed command returns non-zero code.
fdb:ecode ()
Get the last happened error code.

Return value:

the last happened error code. The following error codes are defined: `fdb.ESUCCESS' for success, `fdb.ETHREAD' for threading error, `fdb.EINVALID' for invalid operation, `fdb.ENOFILE' for file not found, `fdb.ENOPERM' for no permission, `fdb.EMETA' for invalid meta data, `fdb.ERHEAD' for invalid record header, `fdb.EOPEN' for open error, `fdb.ECLOSE' for close error, `fdb.ETRUNC' for trunc error, `fdb.ESYNC' for sync error, `fdb.ESTAT' for stat error, `fdb.ESEEK' for seek error, `fdb.EREAD' for read error, `fdb.EWRITE' for write error, `fdb.EMMAP' for mmap error, `fdb.ELOCK' for lock error, `fdb.EUNLINK' for unlink error, `fdb.ERENAME' for rename error, `fdb.EMKDIR' for mkdir error, `fdb.ERMDIR' for rmdir error, `fdb.EKEEP' for existing record, `fdb.ENOREC' for no record found, and `fdb.EMISC' for miscellaneous error.
fdb:errmsg (ecode)
Get the message string corresponding to an error code.

Parameters

  • ecode: the error code. If it is not defined or negative, the last happened error code is specified.

Return value:

the message string of the error code.
fdb:foreach (func)
Process each record atomically.

Parameters

  • func: the iterator function called for each record. It receives two parameters of the key and the value, and returns true to continue iteration or false to stop iteration.

Return value:

If successful, it is true, else, it is false.
fdb:fsiz ()
Get the size of the database file.

Return value:

the size of the database file or 0 if the object does not connect to any database file.
fdb:get (key)
Retrieve a record.

Parameters

  • key: the key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified.

Return value:

If successful, it is the value of the corresponding record. `nil' is returned if no record corresponds.
fdb:iterinit ()
Initialize the iterator. The iterator is used in order to access the key of every record stored in a database.

Return value:

If successful, it is true, else, it is false.
fdb:iternext ()
Get the next key of the iterator. It is possible to access every record by iteration of calling this function. It is allowed to update or remove records whose keys are fetched while the iteration. The order of this traversal access method is ascending of the ID number.

Return value:

If successful, it is the next key, else, it is `nil'. `nil' is returned when no record is to be get out of the iterator.
fdb:open (path, omode)
Open a database file.

Parameters

  • path: the path of the database file.
  • omode: the connection mode: `fdb.OWRITER' as a writer, `fdb.OREADER' as a reader. If the mode is `fdb.OWRITER', the following may be added by bitwise-or: `fdb.OCREAT', which means it creates a new database if not exist, `fdb.OTRUNC', which means it creates a new database regardless if one exists. Both of `fdb.OREADER' and `fdb.OWRITER' can be added to by bitwise-or: `fdb.ONOLCK', which means it opens the database file without file locking, or `fdb.OLCKNB', which means locking is performed without blocking. If it is not defined, `bdb.OREADER' is specified.

Return value:

If successful, it is true, else, it is false.
fdb:optimize (width, limsiz)
Optimize the database file.

Parameters

  • width: the width of the value of each record. If it is not defined or not more than 0, the current setting is not changed.
  • limsiz: the limit size of the database file. If it is not defined or not more than 0, the current setting is not changed.

Return value:

If successful, it is true, else, it is false.
fdb:out (key)
Remove a record.

Parameters

  • key: the key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified.

Return value:

If successful, it is true, else, it is false.
fdb:pairs ()
Get the iterator for generic "for" loop.

Return value:

plural values; the iterator to retrieve the key and the value of the next record, the table itself, and nil.
fdb:path ()
Get the path of the database file.

Return value:

the path of the database file or `nil' if the object does not connect to any database file.
fdb:put (key, value)
Store a record. If a record with the same key exists in the database, it is overwritten.

Parameters

  • key: the key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
fdb:putcat (key, value)
Concatenate a value at the end of the existing record. If there is no corresponding record, a new record is created.

Parameters

  • key: the key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
fdb:putkeep (key, value)
Store a new record. If a record with the same key exists in the database, this method has no effect.

Parameters

  • key: the key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
fdb:range (interval, max)
Get keys with an interval notation.

Parameters

  • interval: the interval notation.
  • max: the maximum number of keys to be fetched. If it is not defined or negative, no limit is specified.

Return value:

a array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
fdb:rnum ()
Get the number of records.

Return value:

the number of records or 0 if the object does not connect to any database file.
fdb:sync ()
Synchronize updated contents with the file and the device. This method is useful when another process connects the same database file.

Return value:

If successful, it is true, else, it is false.
fdb:tranabort ()
Abort the transaction. Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction.

Return value:

If successful, it is true, else, it is false.
fdb:tranbegin ()
Begin the transaction. 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.

Return value:

If successful, it is true, else, it is false.
fdb:trancommit ()
Commit the transaction. Update in the transaction is fixed when it is committed successfully.

Return value:

If successful, it is true, else, it is false.
fdb:tune (width, limsiz)
Set the tuning parameters. The tuning parameters of the database should be set before the database is opened.

Parameters

  • width: the width of the value of each record. If it is not defined or not more than 0, the default value is specified. The default value is 255.
  • limsiz: the limit size of the database file. If it is not defined or not more than 0, the default value is specified. The default value is 268435456.

Return value:

If successful, it is true, else, it is false.
fdb:vanish ()
Remove all records.

Return value:

If successful, it is true, else, it is false.
fdb:vsiz (key)
Get the size of the value of a record.

Parameters

  • key: the key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified.

Return value:

If successful, it is the size of the value of the corresponding record, else, it is -1.
hdb:adddouble (key, num)
Add a real number to a record. 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.

Parameters

  • key: the key.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
hdb:addint (key, num)
Add an integer to a record. 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.

Parameters

  • key: the key.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
hdb:close ()
Close the database file. 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.

Return value:

If successful, it is true, else, it is false.
hdb:copy (path)
Copy the database file. The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress. So, this method is useful to create a backup file of the database file.

Parameters

  • path: the path of the destination file. If it begins with `@', the trailing substring is executed as a command line.

Return value:

If successful, it is true, else, it is false. False is returned if the executed command returns non-zero code.
hdb:ecode ()
Get the last happened error code.

Return value:

the last happened error code. The following error codes are defined: `hdb.ESUCCESS' for success, `hdb.ETHREAD' for threading error, `hdb.EINVALID' for invalid operation, `hdb.ENOFILE' for file not found, `hdb.ENOPERM' for no permission, `hdb.EMETA' for invalid meta data, `hdb.ERHEAD' for invalid record header, `hdb.EOPEN' for open error, `hdb.ECLOSE' for close error, `hdb.ETRUNC' for trunc error, `hdb.ESYNC' for sync error, `hdb.ESTAT' for stat error, `hdb.ESEEK' for seek error, `hdb.EREAD' for read error, `hdb.EWRITE' for write error, `hdb.EMMAP' for mmap error, `hdb.ELOCK' for lock error, `hdb.EUNLINK' for unlink error, `hdb.ERENAME' for rename error, `hdb.EMKDIR' for mkdir error, `hdb.ERMDIR' for rmdir error, `hdb.EKEEP' for existing record, `hdb.ENOREC' for no record found, and `hdb.EMISC' for miscellaneous error.
hdb:errmsg (ecode)
Get the message string corresponding to an error code.

Parameters

  • ecode: the error code. If it is not defined or negative, the last happened error code is specified.

Return value:

the message string of the error code.
hdb:foreach (func)
Process each record atomically.

Parameters

  • func: the iterator function called for each record. It receives two parameters of the key and the value, and returns true to continue iteration or false to stop iteration.

Return value:

If successful, it is true, else, it is false.
hdb:fsiz ()
Get the size of the database file.

Return value:

the size of the database file or 0 if the object does not connect to any database file.
hdb:fwmkeys (prefix, max)
Get forward matching keys. This function may be very slow because every key in the database is scanned.

Parameters

  • prefix: the prefix of the corresponding keys.
  • max: the maximum number of keys to be fetched. If it is negative, no limit is specified.

Return value:

an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
hdb:get (key)
Retrieve a record.

Parameters

  • key: the key.

Return value:

If successful, it is the value of the corresponding record. `nil' is returned if no record corresponds.
hdb:iterinit ()
Initialize the iterator. The iterator is used in order to access the key of every record stored in a database.

Return value:

If successful, it is true, else, it is false.
hdb:iternext ()
Get the next key of the iterator. It is possible to access every record by iteration of calling this method. It is allowed to update or remove records whose keys are fetched while the iteration. However, it is not assured if updating the database is occurred while the iteration. Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.

Return value:

If successful, it is the next key, else, it is `nil'. `nil' is returned when no record is to be get out of the iterator.
hdb:open (path, omode)
Open a database file.

Parameters

  • path: the path of the database file.
  • omode: the connection mode: `hdb.OWRITER' as a writer, `hdb.OREADER' as a reader. If the mode is `hdb.OWRITER', the following may be added by bitwise-or: `hdb.OCREAT', which means it creates a new database if not exist, `hdb.OTRUNC', which means it creates a new database regardless if one exists, `hdb.OTSYNC', which means every transaction synchronizes updated contents with the device. Both of `hdb.OREADER' and `hdb.OWRITER' can be added to by bitwise-or: `hdb.ONOLCK', which means it opens the database file without file locking, or `hdb.OLCKNB', which means locking is performed without blocking. If it is not defined, `hdb.OREADER' is specified.

Return value:

If successful, it is true, else, it is false.
hdb:optimize (bnum, apow, fpow, opts)
Optimize the database file. This method is useful to reduce the size of the database file with data fragmentation by successive updating.

Parameters

  • bnum: the number of elements of the bucket array. If it is not defined or not more than 0, the default value is specified. The default value is two times of the number of records.
  • apow: the size of record alignment by power of 2. If it is not defined or negative, the current setting is not changed.
  • fpow: the maximum number of elements of the free block pool by power of 2. If it is not defined or negative, the current setting is not changed.
  • opts: options by bitwise-or: `hdb.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `hdb.TDEFLATE' specifies that each record is compressed with Deflate encoding, `hdb.TBZIP' specifies that each record is compressed with BZIP2 encoding, `hdb.TTCBS' specifies that each record is compressed with TCBS encoding. If it is not defined or 0xff, the current setting is not changed.

Return value:

If successful, it is true, else, it is false.
hdb:out (key)
Remove a record.

Parameters

  • key: the key.

Return value:

If successful, it is true, else, it is false.
hdb:pairs ()
Get the iterator for generic "for" loop.

Return value:

plural values; the iterator to retrieve the key and the value of the next record, the table itself, and nil.
hdb:path ()
Get the path of the database file.

Return value:

the path of the database file or `nil' if the object does not connect to any database file.
hdb:put (key, value)
Store a record. If a record with the same key exists in the database, it is overwritten.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
hdb:putasync (key, value)
Store a record in asynchronous fashion. If a record with the same key exists in the database, it is overwritten. Records passed to this method are accumulated into the inner buffer and wrote into the file at a blast.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
hdb:putcat (key, value)
Concatenate a value at the end of the existing record. If there is no corresponding record, a new record is created.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
hdb:putkeep (key, value)
Store a new record. If a record with the same key exists in the database, this method has no effect.

Parameters

  • key: the key.
  • value: the value.

Return value:

If successful, it is true, else, it is false.
hdb:rnum ()
Get the number of records.

Return value:

the number of records or 0 if the object does not connect to any database file.
hdb:setcache (rcnum)
Set the caching parameters. The caching parameters of the database should be set before the database is opened.

Parameters

  • rcnum: the maximum number of records to be cached. If it is not defined or not more than 0, the record cache is disabled. It is disabled by default.

Return value:

If successful, it is true, else, it is false.
hdb:setdfunit (dfunit)
Set the unit step number of auto defragmentation.

Parameters

  • dfunit: the unit step number. If it is not more than 0, the auto defragmentation is disabled. It is disabled by default.

Return value:

If successful, it is true, else, it is false.
hdb:setxmsiz (xmsiz)
Set the size of the extra mapped memory. The mapping parameters should be set before the database is opened.

Parameters

  • xmsiz: the size of the extra mapped memory. If it is not defined or not more than 0, the extra mapped memory is disabled. The default size is 67108864.

Return value:

If successful, it is true, else, it is false.
hdb:sync ()
Synchronize updated contents with the file and the device. This method is useful when another process connects the same database file.

Return value:

If successful, it is true, else, it is false.
hdb:tranabort ()
Abort the transaction. Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction.

Return value:

If successful, it is true, else, it is false.
hdb:tranbegin ()
Begin the transaction. 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.

Return value:

If successful, it is true, else, it is false.
hdb:trancommit ()
Commit the transaction. Update in the transaction is fixed when it is committed successfully.

Return value:

If successful, it is true, else, it is false.
hdb:tune (bnum, apow, fpow, opts)
Set the tuning parameters. The tuning parameters of the database should be set before the database is opened.

Parameters

  • bnum: the number of elements of the bucket array. If it is not defined or not more than 0, the default value is specified. The default value is 131071. Suggested size of the bucket array is about from 0.5 to 4 times of the number of all records to be stored.
  • apow: the size of record alignment by power of 2. If it is not defined or negative, the default value is specified. The default value is 4 standing for 2^4=16.
  • fpow: the maximum number of elements of the free block pool by power of 2. If it is not defined or negative, the default value is specified. The default value is 10 standing for 2^10=1024.
  • opts: options by bitwise-or: `hdb.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `hdb.TDEFLATE' specifies that each record is compressed with Deflate encoding, `hdb.TBZIP' specifies that each record is compressed with BZIP2 encoding, `hdb.TTCBS' specifies that each record is compressed with TCBS encoding. If it is not defined, no option is specified.

Return value:

If successful, it is true, else, it is false.
hdb:vanish ()
Remove all records.

Return value:

If successful, it is true, else, it is false.
hdb:vsiz (key)
Get the size of the value of a record.

Parameters

  • key: the key.

Return value:

If successful, it is the size of the value of the corresponding record, else, it is -1.
tdb:adddouble (pkey, num)
Add a real number to a record. The additional value is stored as a decimal string value of a column whose name is "_num". If no record corresponds, a new record with the additional value is stored.

Parameters

  • pkey: the primary key.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
tdb:addint (pkey, num)
Add an integer to a record. The additional value is stored as a decimal string value of a column whose name is "_num". If no record corresponds, a new record with the additional value is stored.

Parameters

  • pkey: the primary key.
  • num: the additional value.

Return value:

If successful, it is the summation value, else, it is `nil'.
tdb:close ()
Close the database file. 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.

Return value:

If successful, it is true, else, it is false.
tdb:copy (path)
Copy the database file. The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress. So, this method is useful to create a backup file of the database file.

Parameters

  • path: the path of the destination file. If it begins with `@', the trailing substring is executed as a command line.

Return value:

If successful, it is true, else, it is false. False is returned if the executed command returns non-zero code.
tdb:ecode ()
Get the last happened error code.

Return value:

the last happened error code. The following error codes are defined: `tdb.ESUCCESS' for success, `tdb.ETHREAD' for threading error, `tdb.EINVALID' for invalid operation, `tdb.ENOFILE' for file not found, `tdb.ENOPERM' for no permission, `tdb.EMETA' for invalid meta data, `tdb.ERHEAD' for invalid record header, `tdb.EOPEN' for open error, `tdb.ECLOSE' for close error, `tdb.ETRUNC' for trunc error, `tdb.ESYNC' for sync error, `tdb.ESTAT' for stat error, `tdb.ESEEK' for seek error, `tdb.EREAD' for read error, `tdb.EWRITE' for write error, `tdb.EMMAP' for mmap error, `tdb.ELOCK' for lock error, `tdb.EUNLINK' for unlink error, `tdb.ERENAME' for rename error, `tdb.EMKDIR' for mkdir error, `tdb.ERMDIR' for rmdir error, `tdb.EKEEP' for existing record, `tdb.ENOREC' for no record found, and `tdb.EMISC' for miscellaneous error.
tdb:errmsg (ecode)
Get the message string corresponding to an error code.

Parameters

  • ecode: the error code. If it is not defined or negative, the last happened error code is specified.

Return value:

the message string of the error code.
tdb:foreach (func)
Process each record atomically.

Parameters

  • func: the iterator function called for each record. It receives two parameters of the key and a table of columns, and returns true to continue iteration or false to stop iteration.

Return value:

If successful, it is true, else, it is false.
tdb:fsiz ()
Get the size of the database file.

Return value:

the size of the database file or 0 if the object does not connect to any database file.
tdb:fwmkeys (prefix, max)
Get forward matching primary keys. This function may be very slow because every key in the database is scanned.

Parameters

  • prefix: the prefix of the corresponding keys.
  • max: the maximum number of keys to be fetched. If it is negative, no limit is specified.

Return value:

an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
tdb:genuid ()
Generate a unique ID number.

Return value:

the new unique ID number or -1 on failure.
tdb:get (pkey)
Retrieve a record.

Parameters

  • pkey: the primary key.

Return value:

If successful, it is a table of the columns of the corresponding record. `nil' is returned if no record corresponds.
tdb:iterinit ()
Initialize the iterator. The iterator is used in order to access the primary key of every record stored in a database.

Return value:

If successful, it is true, else, it is false.
tdb:iternext ()
Get the next primary key of the iterator. It is possible to access every record by iteration of calling this method. It is allowed to update or remove records whose keys are fetched while the iteration. However, it is not assured if updating the database is occurred while the iteration. Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.

Return value:

If successful, it is the next primary key, else, it is `nil'. `nil' is returned when no record is to be get out of the iterator.
tdb:open (path, omode)
Open a database file.

Parameters

  • path: the path of the database file.
  • omode: the connection mode: `tdb.OWRITER' as a writer, `tdb.OREADER' as a reader. If the mode is `tdb.OWRITER', the following may be added by bitwise-or: `tdb.OCREAT', which means it creates a new database if not exist, `tdb.OTRUNC', which means it creates a new database regardless if one exists, `tdb.OTSYNC', which means every transaction synchronizes updated contents with the device. Both of `tdb.OREADER' and `tdb.OWRITER' can be added to by bitwise-or: `tdb.ONOLCK', which means it opens the database file without file locking, or `tdb.OLCKNB', which means locking is performed without blocking. If it is not defined, `tdb.OREADER' is specified.

Return value:

If successful, it is true, else, it is false.
tdb:optimize (bnum, apow, fpow, opts)
Optimize the database file. This method is useful to reduce the size of the database file with data fragmentation by successive updating.

Parameters

  • bnum: the number of elements of the bucket array. If it is not defined or not more than 0, the default value is specified. The default value is two times of the number of records.
  • apow: the size of record alignment by power of 2. If it is not defined or negative, the current setting is not changed.
  • fpow: the maximum number of elements of the free block pool by power of 2. If it is not defined or negative, the current setting is not changed.
  • opts: options by bitwise-or: `tdb.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `tdb.TDEFLATE' specifies that each record is compressed with Deflate encoding, `tdb.TBZIP' specifies that each record is compressed with BZIP2 encoding, `tdb.TTCBS' specifies that each record is compressed with TCBS encoding. If it is not defined or 0xff, the current setting is not changed.

Return value:

If successful, it is true, else, it is false.
tdb:out (pkey)
Remove a record.

Parameters

  • pkey: the primary key.

Return value:

If successful, it is true, else, it is false.
tdb:pairs ()
Get the iterator for generic "for" loop.

Return value:

plural values; the iterator to retrieve the key and the columns of the next record, the table itself, and nil.
tdb:path ()
Get the path of the database file.

Return value:

the path of the database file or `nil' if the object does not connect to any database file.
tdb:put (pkey, cols)
Store a record. If a record with the same key exists in the database, it is overwritten.

Parameters

  • pkey: the primary key.
  • cols: a table containing columns.

Return value:

If successful, it is true, else, it is false.
tdb:putcat (pkey, cols)
Concatenate columns of the existing record. If there is no corresponding record, a new record is created.

Parameters

  • pkey: the primary key.
  • cols: a table containing columns.

Return value:

If successful, it is true, else, it is false.
tdb:putkeep (pkey, cols)
Store a new record. If a record with the same key exists in the database, this method has no effect.

Parameters

  • pkey: the primary key.
  • cols: a table containing columns.

Return value:

If successful, it is true, else, it is false.
tdb:rnum ()
Get the number of records.

Return value:

the number of records or 0 if the object does not connect to any database file.
tdb:setcache (rcnum, lcnum, ncnum)
Set the caching parameters. The caching parameters of the database should be set before the database is opened.

Parameters

  • rcnum: the maximum number of records to be cached. If it is not defined or not more than 0, the record cache is disabled. It is disabled by default.
  • lcnum: the maximum number of leaf nodes to be cached. If it is not defined or not more than 0, the default value is specified. The default value is 1024.
  • ncnum: the maximum number of non-leaf nodes to be cached. If it is not defined or not more than 0, the default value is specified. The default value is 512.

Return value:

If successful, it is true, else, it is false.
tdb:setdfunit (dfunit)
Set the unit step number of auto defragmentation.

Parameters

  • dfunit: the unit step number. If it is not more than 0, the auto defragmentation is disabled. It is disabled by default.

Return value:

If successful, it is true, else, it is false.
tdb:setindex (name, type)
Set a column index.

Parameters

  • name: the name of a column. If the name of an existing index is specified, the index is rebuilt. An empty string means the primary key.
  • type: the index type: `tdb.ITLEXICAL' for lexical string, `tdb.ITDECIMAL' for decimal string, `tdb.ITTOKEN' for token inverted index, `tdb.ITQGRAM' for q-gram inverted index. If it is `tdb.ITOPT', the index is optimized. If it is `tdb.ITVOID', the index is removed. If `tdb.ITKEEP' is added by bitwise-or and the index exists, this method merely returns failure.

Return value:

If successful, it is true, else, it is false.
tdb:setxmsiz (xmsiz)
Set the size of the extra mapped memory. The mapping parameters should be set before the database is opened.

Parameters

  • xmsiz: the size of the extra mapped memory. If it is not defined or not more than 0, the extra mapped memory is disabled. The default size is 67108864.

Return value:

If successful, it is true, else, it is false.
tdb:sync ()
Synchronize updated contents with the file and the device. This method is useful when another process connects the same database file.

Return value:

If successful, it is true, else, it is false.
tdb:tranabort ()
Abort the transaction. Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction.

Return value:

If successful, it is true, else, it is false.
tdb:tranbegin ()
Begin the transaction. 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.

Return value:

If successful, it is true, else, it is false.
tdb:trancommit ()
Commit the transaction. Update in the transaction is fixed when it is committed successfully.

Return value:

If successful, it is true, else, it is false.
tdb:tune (bnum, apow, fpow, opts)
Set the tuning parameters. The tuning parameters of the database should be set before the database is opened.

Parameters

  • bnum: the number of elements of the bucket array. If it is not defined or not more than 0, the default value is specified. The default value is 131071. Suggested size of the bucket array is about from 0.5 to 4 times of the number of all records to be stored.
  • apow: the size of record alignment by power of 2. If it is not defined or negative, the default value is specified. The default value is 4 standing for 2^4=16.
  • fpow: the maximum number of elements of the free block pool by power of 2. If it is not defined or negative, the default value is specified. The default value is 10 standing for 2^10=1024.
  • opts: options by bitwise-or: `tdb.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `tdb.TDEFLATE' specifies that each record is compressed with Deflate encoding, `tdb.TBZIP' specifies that each record is compressed with BZIP2 encoding, `tdb.TTCBS' specifies that each record is compressed with TCBS encoding. If it is not defined, no option is specified.

Return value:

If successful, it is true, else, it is false.
tdb:vanish ()
Remove all records.

Return value:

If successful, it is true, else, it is false.
tdb:vsiz (pkey)
Get the size of the value of a record.

Parameters

  • pkey: the primary key.

Return value:

If successful, it is the size of the value of the corresponding record, else, it is -1.
tdbqry:addcond (name, op, expr)
Add a narrowing condition.

Parameters

  • name: the name of a column. An empty string means the primary key.
  • op: an operation type: `tdbqry.QCSTREQ' for string which is equal to the expression, `tdbqry.QCSTRINC' for string which is included in the expression, `tdbqry.QCSTRBW' for string which begins with the expression, `tdbqry.QCSTREW' for string which ends with the expression, `tdbqry.QCSTRAND' for string which includes all tokens in the expression, `tdbqry.QCSTROR' for string which includes at least one token in the expression, `tdbqry.QCSTROREQ' for string which is equal to at least one token in the expression, `tdbqry.QCSTRRX' for string which matches regular expressions of the expression, `tdbqry.QCNUMEQ' for number which is equal to the expression, `tdbqry.QCNUMGT' for number which is greater than the expression, `tdbqry.QCNUMGE' for number which is greater than or equal to the expression, `tdbqry.QCNUMLT' for number which is less than the expression, `tdbqry.QCNUMLE' for number which is less than or equal to the expression, `tdbqry.QCNUMBT' for number which is between two tokens of the expression, `tdbqry.QCNUMOREQ' for number which is equal to at least one token in the expression, `tdbqry.QCFTSPH' for full-text search with the phrase of the expression, `tdbqry.QCFTSAND' for full-text search with all tokens in the expression, `tdbqry.QCFTSOR' for full-text search with at least one token in the expression, `tdbqry.QCFTSEX' for full-text search with the compound expression. All operations can be flagged by bitwise-or: `tdbqry.QCNEGATE' for negation, `tdbqry.QCNOIDX' for using no index.
  • expr: an operand exression.
tdbqry:hint ()
Get the hint string.

Return value:

the hint string.
tdbqry:kwic (cols, name, width, opts)
Generate keyword-in-context strings.

Parameters

  • cols: a table containing columns.
  • name: the name of a column. If it is not defined, the first column of the query is specified.
  • width: the width of strings picked up around each keyword. If it is not defined or negative, the whole text is picked up.
  • opts: options by bitwise-or: `tdbqry.KWMUTAB' specifies that each keyword is marked up between two tab characters, `tdbqry.KWMUCTRL' specifies that each keyword is marked up by the STX (0x02) code and the ETX (0x03) code, `tdbqry.KWMUBRCT' specifies that each keyword is marked up by the two square brackets, `tdbqry.KWNOOVER' specifies that each context does not overlap, `tdbqry.KWPULEAD' specifies that the lead string is picked up forcibly. If it is not defined, no option is specified.

Return value:

an array of strings around keywords.
tdbqry:metasearch (others, type)
Retrieve records with multiple query objects and get the set of the result.

Parameters

  • others: an array of the query objects except for the self object.
  • type: a set operation type: `tdbqry.MSUNION' for the union set, `tdbqry.MSISECT' for the intersection set, `tdbqry.MSDIFF' for the difference set. If it is not defined, `tdbqry.MSUNION' is specified.

Return value:

an array of the primary keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds. If the first query object has the order setting, the result array is sorted by the order.
tdbqry:proc ()
Process each corresponding record. This method needs a block parameter of the iterator called for each record. The block receives two parameters. The first parameter is the primary key. The second parameter is a table containing columns. It returns flags of the post treatment by bitwise-or: `tdbqry.QPPUT' to modify the record, `tdbqry.QPOUT' to remove the record, `tdbqry.QPSTOP' to stop the iteration.

Return value:

If successful, it is true, else, it is false.
tdbqry:search ()
Execute the search.

Return value:

an array of the primary keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
tdbqry:searchout ()
Remove each corresponding record.

Return value:

If successful, it is true, else, it is false.
tdbqry:setlimit (max, skip)
Set the maximum number of records of the result.

Parameters

  • max: the maximum number of records of the result. If it is not defined or negative, no limit is specified.
  • skip: the maximum number of records of the result. If it is not defined or not more than 0, no record is skipped.
tdbqry:setorder (name, type)
Set the order of the result.

Parameters

  • name: the name of a column. An empty string means the primary key.
  • type: the order type: `tdbqry.QOSTRASC' for string ascending, `tdbqry.QOSTRDESC' for string descending, `tdbqry.QONUMASC' for number ascending, `tdbqry.QONUMDESC' for number descending. If it is not defined, `tdbqry.QOSTRASC' is specified.
tokyocabinet.adbnew ()
Create an abstract database object. Abstract database is a set of interfaces to use on-memory hash database, on-memory tree database, hash database, B+ tree database, fixed-length database, and table database with the same API. Before operations to store or retrieve records, it is necessary to connect the abstract database object to the concrete one. The method `open' is used to open a concrete database and the method `close' is used to close the database. To avoid data missing or corruption, it is important to close every database instance 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.

Return value:

the new abstract database object.
tokyocabinet.bdbcurnew (bdb)
Create a cursor object of a B+ tree database object. Cursor is a mechanism to access each record of B+ tree database in ascending or descending order. The cursor is available only after initialization with the `cur:first' or the `cur:jump' methods and so on. Moreover, the position of the cursor will be indefinite when the database is updated after the initialization of the cursor.

Parameters

  • bdb: the B+ tree database object.
tokyocabinet.bdbnew ()
Create a B+ tree database object. B+ tree database is a file containing a B+ tree and is handled with the B+ tree database API. Before operations to store or retrieve records, it is necessary to open a database file and connect the B+ tree database object to it. 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.

Return value:

the new B+ tree database object.
tokyocabinet.bit (mode, num, aux)
Perform bit operation of an integer.

Parameters

  • mode: the operator; "and" for bitwise-and operation, "or" for bitwise-or operation, "xor" for bitwise-xor operation, "not" for bitwise-not operation, "left" for left shift operation, "right" for right shift operation.
  • num: the integer, which is treated as an unsigned 32-bit integer.
  • aux: the auxiliary operand for some operators.

Return value:

the result value.
tokyocabinet.chdir (path)
Change the current working directory.

Parameters

  • path: the path of the directory.

Return value:

If successful, it is true, else, it is false.
tokyocabinet.codec (mode, str)
Encode or decode a string.

Parameters

  • mode: the encoding method; "url" for URL encoding, "~url" for URL decoding, "base" for Base64 encoding, "~base" for Base64 decoding, "hex" for hexadecimal encoding, "~hex" for hexadecimal decoding, "pack" for PackBits encoding, "~pack" for PackBits decoding, "tcbs" for TCBS encoding, "~tcbs" for TCBS decoding, "deflate" for Deflate encoding, "~deflate" for Deflate decoding, "gzip" for GZIP encoding, "~gzip" for GZIP decoding, "bzip" for BZIP2 encoding, "~bzip" for BZIP2 decoding, "xml" for XML escaping, "~xml" for XML unescaping.
  • str: the string.

Return value:

the encoded or decoded string.
tokyocabinet.dist (astr, bstr, isutf)
Calculate the edit distance of two UTF-8 strings.

Parameters

  • astr: a string.
  • bstr: the other string.
  • isutf: whether to calculate cost by Unicode character. If it is not defined, false is specified and calculate cost by ASCII character.

Return value:

the edit distance which is known as the Levenshtein distance.
tokyocabinet.fdbnew ()
Create a fixed-length database object. Fixed-Length database is a file containing a fixed-length table and is handled with the fixed-length database API. Before operations to store or retrieve records, it is necessary to open a database file and connect the fixed-length database object to it. 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.

Return value:

the new fixed-length database object.
tokyocabinet.glob (pattern)
Find pathnames matching a pattern.

Parameters

  • pattern: the matching pattern. "?" and "*" are meta characters.

Return value:

an array of matched paths. If no path is matched, an empty array is returned.
tokyocabinet.hash (mode, str)
Get the hash value of a string.

Parameters

  • mode: the hash method; "md5" for MD5 in hexadecimal format, "md5raw" for MD5 in raw format, "crc32" for CRC32 checksum number.
  • str: the string.

Return value:

the hash value.
tokyocabinet.hdbnew ()
Create a hash database object. Hash database is a file containing a hash table and is handled with the hash database API. Before operations to store or retrieve records, it is necessary to open a database file and connect the hash database object to it. 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.

Return value:

the new hash database object.
tokyocabinet.isect (ary, ...)
Calculate the intersection set of arrays.

Parameters

  • ary: the arrays. Arbitrary number of arrays can be specified as the parameter list.
  • ...:

Return value:

the array of the intersection set.
tokyocabinet.mkdir (path)
Create a directory.

Parameters

  • path: the path of the directory.

Return value:

If successful, it is true, else, it is false.
tokyocabinet.pack (format, ary, ...)
Serialize an array of numbers into a string.

Parameters

  • format: the format string. It should be composed of conversion characters; `c' for int8_t, `C' for uint8_t, `s' for int16_t, `S' for uint16_t, `i' for int32_t, `I' for uint32_t, `l' for int64_t, `L' for uint64_t, `f' for float, `d' for double, `n' for uint16_t in network byte order, `N' for uint32_t in network byte order, `M' for uint64_t in network byte order, and `w' for BER encoding. They can be trailed by a numeric expression standing for the iteration count or by `*' for the rest all iteration.
  • ary: the array of numbers. It can be trailed optional arguments, which are treated as additional elements of the array.
  • ...:

Return value:

the serialized string.
tokyocabinet.regex (str, pattern, alt)
Perform pattern matching or replacement with regular expressions.

Parameters

  • str: the source string.
  • pattern: the pattern of regular expressions.
  • alt: the alternative string corresponding for the pattern. If it is not defined, matching check is performed.

Return value:

If the alternative string is specified, the converted string is returned. If the alternative string is not specified, the boolean value of whether the source string matches the pattern is returned.
tokyocabinet.remove (path)
Remove a file or a directory and its sub ones recursively.

Parameters

  • path: the path of the link.

Return value:

If successful, it is true, else, it is false.
tokyocabinet.sleep (sec)
Suspend execution for the specified interval.

Parameters

  • sec: the interval in seconds.

Return value:

If successful, it is true, else, it is false.
tokyocabinet.split (str, delims)
Split a string into substrings.

Parameters

  • str: the string
  • delims: a string including separator characters. If it is not defined, the zero code is specified.

Return value:

an array of substrings.
tokyocabinet.stat (path)
Get the status of a file.

Parameters

  • path: the path of the file.

Return value:

If successful, it is a table containing status, else, it is `nil'. There are keys of status name; "dev", "ino", "mode", "nlink", "uid", "gid", "rdev", "size", "blksize", "blocks", "atime", "mtime", "ctime", which have same meanings of the POSIX "stat" call. Additionally, "_regular" for whether the file is a regular file, "_directory" for whether the file is a directory, "_readable" for whether the file is readable by the process, "_writable" for whether the file is writable by the process, "_executable" for whether the file is executable by the process, "_realpath" for the real path of the file, are supported.
tokyocabinet.strstr (str, pattern, alt)
Perform substring matching or replacement without evaluating any meta character.

Parameters

  • str: the source string.
  • pattern: the matching pattern.
  • alt: the alternative string corresponding for the pattern. If it is not defined, matching check is performed.

Return value:

If the alternative string is specified, the converted string is returned. If the alternative string is not specified, the index of the substring matching the given pattern or 0 is returned.
tokyocabinet.tablenew (anum, rnum)
Create a table with specifying the number of array elements and the number of hash records.

Parameters

  • anum: the expected number of array elements. If it is not defined, 0 is specified.
  • rnum: the expected number of hash records. If it is not defined, 0 is specified.

Return value:

the created empty table.
tokyocabinet.tdbnew ()
Create a table database object. Table database is a file containing records composed of the primary keys and arbitrary columns and is handled with the table database API. Before operations to store or retrieve records, it is necessary to open a database file and connect the table database object to it. 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.

Return value:

the new table database object.
tokyocabinet.tdbqrynew (tdb)
Create a query object of a table database object. Query is a mechanism to search for and retrieve records corresponding conditions from table database.

Parameters

  • tdb: the table database object.
tokyocabinet.time ()
Get the time of day in seconds.

Return value:

the time of day in seconds. The accuracy is in microseconds.
tokyocabinet.ucs (data)
Convert a UTF-8 string into a UCS-2 array or its inverse.

Parameters

  • data: the target data. If it is a string, convert it into a UCS-array. If it is an array, convert it into a UTF-8 string.

Return value:

the result data.
tokyocabinet.union (ary, ...)
Calculate the union set of arrays.

Parameters

  • ary: the arrays. Arbitrary number of arrays can be specified as the parameter list.
  • ...:

Return value:

the array of the union set.
tokyocabinet.unpack (format, str)
Deserialize a binary string into an array of numbers.

Parameters

  • format: the format string. It should be composed of conversion characters as with `tokyocabinet.pack'.
  • str: the binary string.

Return value:

the deserialized array.
Tokyo Cabinet Manual