LuaDoc

• Index

Modules

• kyotocabinet

Module kyotocabinet

The Lua binding of Kyoto Cabinet.

Functions

DB:delete_ptr (ptr)	Delete a database object.
DB:new (ptr)	Create a database object.
DB:new_ptr ()	Create a database object.
DB:process (proc, path, mode)	Process a database by a functor.
Error:new (code, message)	Create an error object.
FileProcessor:new ()	Create a file processor object.
Visitor:new ()	Create a visitor object.
arraydump (src)	Serialize an array into a string.
arrayload (src)	Deserialize a string into an array.
atof (str)	Convert a string to a real number.
atoi (str)	Convert a string to an integer.
atoix (str)	Convert a string with a metric prefix to an integer.
bit (mode, num, aux)	Perform bit operation of an integer.
codec (mode, str)	Encode or decode a string.
cursor:__call (db)	Get a pair of the key and the value of the current record.
cursor:__tostring ()	Get the string expression.
cursor:accept (visitor, writable, step)	Accept a visitor to the current record.
cursor:db ()	Get the database object.
cursor:disable ()	Disable the cursor.
cursor:error ()	Get the last happened error.
cursor:get (step)	Get a pair of the key and the value of the current record.
cursor:get_key (step)	Get the key of the current record.
cursor:get_value (step)	Get the value of the current record.
cursor:jump (key)	Jump the cursor to a record for forward scan.
cursor:jump_back (key)	Jump the cursor to a record for backward scan.
cursor:remove ()	Remove the current record.
cursor:seize ()	Get a pair of the key and the value of the current record and remove it atomically.
cursor:set_value (value, step)	Set the value of the current record.
cursor:step ()	Step the cursor to the next record.
cursor:step_back ()	Step the cursor to the previous record.
db:__index (key)	Retrieve the value of a record.
db:__newindex (key, value)	Set the value of a record.
db:__tostring ()	Get the string expression.
db:accept (key, visitor, writable)	Accept a visitor to a record.
db:accept_bulk (keys, visitor, writable)	Accept a visitor to multiple records at once.
db:add (key, value)	Add a record.
db:append (key, value)	Append the value of a record.
db:begin_transaction (hard)	Begin transaction.
db:cas (key, oval, nval)	Perform compare-and-swap.
db:check (key)	Check the existence of a record.
db:clear ()	Remove all records.
db:close ()	Close the database file.
db:copy (dest)	Create a copy of the database file.
db:count ()	Get the number of records.
db:cursor ()	Create a cursor object.
db:cursor_process (proc)	Process a cursor by a functor.
db:dump_snapshot (dest)	Dump records into a snapshot file.
db:end_transaction (commit)	End transaction.
db:get (key)	Retrieve the value of a record.
db:get_bulk (keys, atomic)	Retrieve records at once.
db:increment (key, num, orig)	Add a number to the numeric integer value of a record.
db:increment_double (key, num, orig)	Add a number to the numeric double value of a record.
db:iterate (visitor, writable)	Iterate to accept a visitor for each record.
db:load_snapshot (src)	Load records from a snapshot file.
db:mapreduce (map, reduce, tmppath, opts, dbnum, clim, cbnum, log, proc)	Execute a MapReduce process.
db:match_prefix (prefix, max)	Get keys matching a prefix string.
db:match_regex (regex, max)	Get keys matching a regular expression string.
db:match_similar (origin, range, utf, max)	Get keys similar to a string in terms of the levenshtein distance.
db:merge (srcary, mode)	Merge records from other databases.
db:occupy (writable, proc)	Occupy database by locking and do something meanwhile.
db:open (path, mode)	Open a database file.
db:pairs ()	Create three objects for the generic "for" loop.
db:path ()	Get the path of the database file.
db:remove (key)	Remove a record.
db:remove_bulk (keys, atomic)	Remove records at once.
db:replace (key, value)	Replace the value of a record.
db:seize (key)	Retrieve the value of a record and remove it atomically.
db:set (key, value)	Set the value of a record.
db:set_bulk (recs, atomic)	Store records at once.
db:size ()	Get the size of the database file.
db:status ()	Get the miscellaneous status information.
db:synchronize (hard, proc)	Synchronize updated contents with the file and the device.
db:transaction (proc, hard)	Perform entire transaction by a functor.
error:__tostring ()	Get the string expression.
error:code ()	Get the error code.
error:message ()	Get the supplement message.
error:name ()	Get the readable string of the code.
error:set (code, message)	Set the error information.
fileprocessor:process (path, count, size)	Process the database file.
hash_fnv (str)	Get the hash value of a string by FNV hashing.
hash_murmur (str)	Get the hash value of a string by MurMur hashing.
levdist (a, b, utf)	Calculate the levenshtein distance of two strings.
mapdump (src)	Serialize a map into a string.
mapload (src)	Deserialize a string into a map.
pack (format, ary, ...)	Serialize an array of numbers into a string.
regex (str, pattern, alt)	Perform pattern matching or replacement with regular expressions.
sleep (sec)	Suspend execution of the current thread.
split (str, delims)	Split a string into substrings.
strbwm (str, pattern)	Perform backward matching without evaluating any meta character.
strfwm (str, pattern)	Perform forward matching without evaluating any meta character.
strstr (str, pattern, alt)	Perform substring matching or replacement without evaluating any meta character.
time ()	Get the time of day in seconds.
unpack (format, str)	Deserialize a binary string into an array of numbers.
visitor:visit_after ()	Postprocess the main operations.
visitor:visit_before ()	Preprocess the main operations.
visitor:visit_empty (key)	Visit a empty record space.
visitor:visit_full (key, value)	Visit a record.

Tables

Cursor	Interface of cursor to indicate a record.
DB	Interface of database abstraction.
Error	Error data.
FileProcessor	Interface to process the database file.
Visitor	Interface to access a record.
kc	Module object returned by the "require" expression.

Functions

DB:delete_ptr (ptr)

Delete a database object.

Parameters

• ptr: a light user data of the pointer to the database object.

Return value:

always nil.

DB:new (ptr)

Create a database object.

Parameters

• ptr: a light user data of the pointer to a database object to use internally. If it is omitted, the internal database object is created and destroyed implicitly.

Return value:

the database object.

DB:new_ptr ()

Create a database object.

Return value:

a light user data of the pointer to the created database object. It should be released with the delete_ptr method when it is no longer in use.

DB:process (proc, path, mode)

Process a database by a functor.

Parameters

• proc: the functor to process the database, whose object is passd as the parameter.
• path: the same to the one of the open method.
• mode: the same to the one of the open method.

Return value:

nil on success, or an error object on failure.

Error:new (code, message)

Create an error object.

Parameters

• code: the error code.
• message: the supplement message.

Return value:

the error object.

FileProcessor:new ()

Create a file processor object.

Return value:

the file processor object.

Visitor:new ()

Create a visitor object.

Return value:

the visitor object.

arraydump (src)

Serialize an array into a string.

Parameters

• src: the source table.

Return value:

the result string.

arrayload (src)

Deserialize a string into an array.

Parameters

• src: the source string.

Return value:

the result map.

atof (str)

Convert a string to a real number.

Parameters

• str: the string.

Return value:

the real number. If the string does not contain numeric expression, 0.0 is returned.

atoi (str)

Convert a string to an integer.

Parameters

• str: the string.

Return value:

the integer. If the string does not contain numeric expression, 0 is returned.

atoix (str)

Convert a string with a metric prefix to an integer.

Parameters

• str: the string, which can be trailed by a binary metric prefix. "K", "M", "G", "T", "P", and "E" are supported. They are case-insensitive.

Return value:

the integer. If the string does not contain numeric expression, 0 is returned. If the integer overflows the domain, INT64_MAX or INT64_MIN is returned according to the sign.

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.

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, "zlib" for ZLIB raw compressing, "~zlib" for ZLIB raw decompressing, "deflate" for ZLIB deflate compressing, "~deflate" for ZLIB deflate decompressing, "gzip" for ZLIB gzip compressing, "~gzip" for ZLIB gzip decompressing.
• str: the string.

Return value:

the result string.

cursor:__call (db)

Get a pair of the key and the value of the current record.

Parameters

• db: ignored. This is just for compatibility with the "next" function for the generic "for" loop.

Usage:

If the cursor is invalidated, nil is returned.

Return value:

a pair of the key and the value of the current record, or nil on failure.

cursor:__tostring ()

Get the string expression.

Return value:

the string expression.

cursor:accept (visitor, writable, step)

Accept a visitor to the current record.

Parameters

• visitor: a visitor object which implements the Visitor interface, or a function object which receives the key and the value.
• writable: true for writable operation, or false for read-only operation. If it is omitted, true is specified.
• step: true to move the cursor to the next record, or false for no move. If it is omitted, false is specified.

Usage:

The operation for each record is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

Return value:

true on success, or false on failure.

cursor:db ()

Get the database object.

Return value:

the database object.

cursor:disable ()

Disable the cursor.

Usage:

This method should be called explicitly when the cursor is no longer in use.

Return value:

always nil.

cursor:error ()

Get the last happened error.

Return value:

the last happened error.

cursor:get (step)

Get a pair of the key and the value of the current record.

Parameters

• step: true to move the cursor to the next record, or false for no move. If it is omitted, false is specified.

Usage:

If the cursor is invalidated, nil is returned.

Return value:

a pair of the key and the value of the current record, or nil on failure.

cursor:get_key (step)

Get the key of the current record.

Parameters

• step: true to move the cursor to the next record, or false for no move. If it is omitted, false is specified.

Usage:

If the cursor is invalidated, nil is returned.

Return value:

the key of the current record, or nil on failure.

cursor:get_value (step)

Get the value of the current record.

Parameters

• step: true to move the cursor to the next record, or false for no move. If it is omitted, false is specified.

Usage:

If the cursor is invalidated, nil is returned.

Return value:

the value of the current record, or nil on failure.

cursor:jump (key)

Jump the cursor to a record for forward scan.

Parameters

• key: the key of the destination record. If it is omitted, the destination is the first record.

Return value:

true on success, or false on failure.

cursor:jump_back (key)

Jump the cursor to a record for backward scan.

Parameters

• key: the key of the destination record. If it is omitted, the destination is the last record.

Usage:

This method is dedicated to tree databases. Some database types, especially hash databases, will provide a dummy implementation.

Return value:

true on success, or false on failure.

cursor:remove ()

Remove the current record.

Usage:

If no record corresponds to the key, false is returned. The cursor is moved to the next record implicitly.

Return value:

true on success, or false on failure.

cursor:seize ()

Get a pair of the key and the value of the current record and remove it atomically.

Usage:

If the cursor is invalidated, nil is returned. The cursor is moved to the next record implicitly.

Return value:

a pair of the key and the value of the current record, or nil on failure.

cursor:set_value (value, step)

Set the value of the current record.

Parameters

• value: the value.
• step: true to move the cursor to the next record, or false for no move. If it is omitted, false is specified.

Return value:

true on success, or false on failure.

cursor:step ()

Step the cursor to the next record.

Return value:

true on success, or false on failure.

cursor:step_back ()

Step the cursor to the previous record.

Usage:

This method is dedicated to tree databases. Some database types, especially hash databases, will provide a dummy implementation.

Return value:

true on success, or false on failure.

db:__index (key)

Retrieve the value of a record.

Parameters

• key: the key.

Return value:

the value of the corresponding record, or nil on failure.

db:__newindex (key, value)

Set the value of a record.

Parameters

• key: the key.
• value: the value. If it is nil, the record is removed.

Usage:

If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.

Return value:

true on success, or false on failure.

db:__tostring ()

Get the string expression.

Return value:

the string expression.

db:accept (key, visitor, writable)

Accept a visitor to a record.

Parameters

• key: the key.
• visitor: a visitor object which implements the Visitor interface, or a function object which receives the key and the value.
• writable: true for writable operation, or false for read-only operation. If it is omitted, true is specified.

Usage:

The operation for each record is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

Return value:

true on success, or false on failure.

db:accept_bulk (keys, visitor, writable)

Accept a visitor to multiple records at once.

Parameters

• keys: specifies an array of the keys.
• visitor: a visitor object which implements the Visitor interface, or a function object which receives the key and the value.
• writable: true for writable operation, or false for read-only operation. If it is omitted, true is specified.

Usage:

The operations for specified records are performed atomically and other threads accessing the same records are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

Return value:

true on success, or false on failure.

db:add (key, value)

Add a record.

Parameters

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

Usage:

If no record corresponds to the key, a new record is created. If the corresponding record exists, the record is not modified and false is returned.

Return value:

true on success, or false on failure.

db:append (key, value)

Append the value of a record.

Parameters

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

Usage:

If no record corresponds to the key, a new record is created. If the corresponding record exists, the given value is appended at the end of the existing value.

Return value:

true on success, or false on failure.

db:begin_transaction (hard)

Begin transaction.

Parameters

• hard: true for physical synchronization with the device, or false for logical synchronization with the file system. If it is omitted, false is specified.

Return value:

true on success, or false on failure.

db:cas (key, oval, nval)

Perform compare-and-swap.

Parameters

• key: the key.
• oval: the old value. nil means that no record corresponds.
• nval: the new value. nil means that the record is removed.

Return value:

true on success, or false on failure.

db:check (key)

Check the existence of a record.

Parameters

• key: the key.

Return value:

the size of the value, or -1 on failure.

db:clear ()

Remove all records.

Return value:

true on success, or false on failure.

db:close ()

Close the database file.

Return value:

true on success, or false on failure.

db:copy (dest)

Create a copy of the database file.

Parameters

• dest: the path of the destination file.

Return value:

true on success, or false on failure.

db:count ()

Get the number of records.

Return value:

the number of records, or -1 on failure.

db:cursor ()

Create a cursor object.

Return value:

the return value is the created cursor object. Each cursor should be disabled with the Cursor#disable method when it is no longer in use.

db:cursor_process (proc)

Process a cursor by a functor.

Parameters

• proc: the functor of operations for the cursor. The cursor is disabled implicitly after the block.

Return value:

always nil.

db:dump_snapshot (dest)

Dump records into a snapshot file.

Parameters

• dest: the name of the destination file.

Return value:

true on success, or false on failure.

db:end_transaction (commit)

End transaction.

Parameters

• commit: true to commit the transaction, or false to abort the transaction. If it is omitted, true is specified.

Return value:

true on success, or false on failure.

db:get (key)

Retrieve the value of a record.

Parameters

• key: the key.

Return value:

the value of the corresponding record, or nil on failure.

db:get_bulk (keys, atomic)

Retrieve records at once.

Parameters

• keys: an array of the keys of the records to retrieve.
• atomic: true to perform all operations atomically, or false for non-atomic operations. If it is omitted, true is specified.

Return value:

a table of retrieved records, or nil on failure.

db:increment (key, num, orig)

Add a number to the numeric integer value of a record.

Parameters

• key: the key.
• num: the additional number. If it is omitted, 0 is specified.
• orig: the origin number if no record corresponds to the key. If it is omitted, 0 is specified. If it is negative infinity and no record corresponds, this method fails. If it is positive infinity, the value is set as the additional number regardless of the current value.

Usage:

The value is serialized as an 8-byte binary integer in big-endian order, not a decimal string. If existing value is not 8-byte, this method fails.

Return value:

the result value, or nil on failure.

db:increment_double (key, num, orig)

Add a number to the numeric double value of a record.

Parameters

• key: the key.
• num: the additional number. If it is omitted, 0 is specified.
• orig: the origin number if no record corresponds to the key. If it is omitted, 0 is specified. If it is negative infinity and no record corresponds, this method fails. If it is positive infinity, the value is set as the additional number regardless of the current value.

Usage:

The value is serialized as an 16-byte binary fixed-point number in big-endian order, not a decimal string. If existing value is not 16-byte, this method fails.

Return value:

the result value, or nil on failure.

db:iterate (visitor, writable)

Iterate to accept a visitor for each record.

Parameters

• visitor: a visitor object which implements the Visitor interface, or a function object which receives the key and the value.
• writable: true for writable operation, or false for read-only operation. If it is omitted, true is specified.

Usage:

The whole iteration is performed atomically and other threads are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

Return value:

true on success, or false on failure.

db:load_snapshot (src)

Load records from a snapshot file.

Parameters

• src: the name of the source file.

Return value:

true on success, or false on failure.

db:mapreduce (map, reduce, tmppath, opts, dbnum, clim, cbnum, log, proc)

Execute a MapReduce process.

Parameters

• map: a function to map a record data. It is called for each record in the database and receives the key, the value, and a function to emit the mapped records. The emitter function receives a key and a value. The mapper function should return true normally or false on failure.
• reduce: a function to reduce a record data. It is called for each record generated by emitted records by the map function and receives the key and a function to iterate to get each value. The reducer function should return true normally or false on failure.
• tmppath: the path of a directory for the temporary data storage. If it is omitted, temporary data are handled on memory.
• opts: the optional features by bitwise-or: DB.XNOLOCK to avoid locking against update operations by other threads, DB.XNOCOMP to avoid compression of temporary databases.
• dbnum: the number of temporary databases. If it is omitted, the default setting is specified.
• clim: the limit size of the internal cache. If it is omitted, the default setting is specified.
• cbnum: the bucket number of the internal cache. If it is omitted, the default setting is specified.
• log: a function to log each progression message. If it is omitted, log messages are ignored.
• proc: a function called before the mapper, between the mapper and the reducer, and after the reducer. In the first two calls, the function receives a function to emit the mapped records. If it is omitted, such triggers are ignored.

Return value:

true on success, or false on failure.

db:match_prefix (prefix, max)

Get keys matching a prefix string.

Parameters

• prefix: the prefix string.
• max: the maximum number to retrieve. If it is omitted or negative, no limit is specified.

Return value:

an array of matching keys, or nil on failure.

db:match_regex (regex, max)

Get keys matching a regular expression string.

Parameters

• regex: the regular expression string.
• max: the maximum number to retrieve. If it is omitted or negative, no limit is specified.

Return value:

an array of matching keys, or nil on failure.

db:match_similar (origin, range, utf, max)

Get keys similar to a string in terms of the levenshtein distance.

Parameters

• origin: the origin string.
• range: the maximum distance of keys to adopt. If it is omitted, 1 is specified.
• utf: flag to treat keys as UTF-8 strings. If it is omitted, false is specified.
• max: the maximum number to retrieve. If it is omitted or negative, no limit is specified.

Return value:

an array of matching keys, or nil on failure.

db:merge (srcary, mode)

Merge records from other databases.

Parameters

• srcary: an array of the source detabase objects.
• mode: the merge mode. DB.MSET to overwrite the existing value, DB.MADD to keep the existing value, DB.MAPPEND to append the new value. If it is omitted, DB.MSET is specified.

Return value:

true on success, or false on failure.

db:occupy (writable, proc)

Occupy database by locking and do something meanwhile.

Parameters

• writable: true to use writer lock, or false to use reader lock. If it is omitted, false is specified.
• proc: a processor object which implements the FileProcessor interface, or a function object which receives the same parameters. If it is omitted or nil, no processing is performed.

Usage:

The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

Return value:

true on success, or false on failure.

db:open (path, mode)

Open a database file.

Parameters

• path: the path of a database file. If it is "-", the database will be a prototype hash database. If it is "+", the database will be a prototype tree database. If it is ":", the database will be a stash database. If it is "*", the database will be a cache hash database. If it is "%", the database will be a cache tree database. If its suffix is ".kch", the database will be a file hash database. If its suffix is ".kct", the database will be a file tree database. If its suffix is ".kcd", the database will be a directory hash database. If its suffix is ".kcf", the database will be a directory tree database. If its suffix is ".kcx", the database will be a plain text database. Otherwise, this function fails. Tuning parameters can trail the name, separated by "#". Each parameter is composed of the name and the value, separated by "=". If the "type" parameter is specified, the database type is determined by the value in "-", "+", ":", "*", "%", "kch", "kct", "kcd", kcf", and "kcx". All database types support the logging parameters of "log", "logkinds", and "logpx". The prototype hash database and the prototype tree database do not support any other tuning parameter. The stash database supports "bnum". The cache hash database supports "opts", "bnum", "zcomp", "capcnt", "capsiz", and "zkey". The cache tree database supports all parameters of the cache hash database except for capacity limitation, and supports "psiz", "rcomp", "pccap" in addition. The file hash database supports "apow", "fpow", "opts", "bnum", "msiz", "dfunit", "zcomp", and "zkey". The file tree database supports all parameters of the file hash database and "psiz", "rcomp", "pccap" in addition. The directory hash database supports "opts", "zcomp", and "zkey". The directory tree database supports all parameters of the directory hash database and "psiz", "rcomp", "pccap" in addition. The plain text database does not support any other tuning parameter.
• mode: the connection mode. DB.OWRITER as a writer, DB.OREADER as a reader. The following may be added to the writer mode by bitwise-or: DB.OCREATE, which means it creates a new database if the file does not exist, DB.OTRUNCATE, which means it creates a new database regardless if the file exists, DB.OAUTOTRAN, which means each updating operation is performed in implicit transaction, DB.OAUTOSYNC, which means each updating operation is followed by implicit synchronization with the file system. The following may be added to both of the reader mode and the writer mode by bitwise-or: DB.ONOLOCK, which means it opens the database file without file locking, DB.OTRYLOCK, which means locking is performed without blocking, DB.ONOREPAIR, which means the database file is not repaired implicitly even if file destruction is detected. If it is omitted, DB.OWRITER + DB.OCREATE is specified.

Usage:

The tuning parameter "log" is for the original "tune_logger" and the value specifies the path of the log file, or "-" for the standard output, or "+" for the standard error. "logkinds" specifies kinds of logged messages and the value can be "debug", "info", "warn", or "error". "logpx" specifies the prefix of each log message. "opts" is for "tune_options" and the value can contain "s" for the small option, "l" for the linear option, and "c" for the compress option. "bnum" corresponds to "tune_bucket". "zcomp" is for "tune_compressor" and the value can be "zlib" for the ZLIB raw compressor, "def" for the ZLIB deflate compressor, "gz" for the ZLIB gzip compressor, "lzo" for the LZO compressor, "lzma" for the LZMA compressor, or "arc" for the Arcfour cipher. "zkey" specifies the cipher key of the compressor. "capcnt" is for "cap_count". "capsiz" is for "cap_size". "psiz" is for "tune_page". "rcomp" is for "tune_comparator" and the value can be "lex" for the lexical comparator, "dec" for the decimal comparator, "lexdesc" for the lexical descending comparator, or "decdesc" for the decimal descending comparator. "pccap" is for "tune_page_cache". "apow" is for "tune_alignment". "fpow" is for "tune_fbp". "msiz" is for "tune_map". "dfunit" is for "tune_defrag". Every opened database must be closed by the DB::close method when it is no longer in use. It is not allowed for two or more database objects in the same process to keep their connections to the same database file at the same time.

Return value:

true on success, or false on failure.

db:pairs ()

Create three objects for the generic "for" loop.

Return value:

multiple values composed of the "next" functor, the database object itself, and nil.

db:path ()

Get the path of the database file.

Return value:

the path of the database file, or nil on failure.

db:remove (key)

Remove a record.

Parameters

• key: the key.

Usage:

If no record corresponds to the key, false is returned.

Return value:

true on success, or false on failure.

db:remove_bulk (keys, atomic)

Remove records at once.

Parameters

• keys: an array of the keys of the records to remove.
• atomic: true to perform all operations atomically, or false for non-atomic operations. If it is omitted, true is specified.

Return value:

the number of removed records, or -1 on failure.

db:replace (key, value)

Replace the value of a record.

Parameters

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

Usage:

If no record corresponds to the key, no new record is created and false is returned. If the corresponding record exists, the value is modified.

Return value:

true on success, or false on failure.

db:seize (key)

Retrieve the value of a record and remove it atomically.

Parameters

• key: the key.

Return value:

the value of the corresponding record, or nil on failure.

db:set (key, value)

Set the value of a record.

Parameters

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

Usage:

If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.

Return value:

true on success, or false on failure.

db:set_bulk (recs, atomic)

Store records at once.

Parameters

• recs: a table of the records to store.
• atomic: true to perform all operations atomically, or false for non-atomic operations. If it is omitted, true is specified.

Return value:

the number of stored records, or -1 on failure.

db:size ()

Get the size of the database file.

Return value:

the size of the database file in bytes, or -1 on failure.

db:status ()

Get the miscellaneous status information.

Return value:

a table of the status information, or nil on failure.

db:synchronize (hard, proc)

Synchronize updated contents with the file and the device.

Parameters

• hard: true for physical synchronization with the device, or false for logical synchronization with the file system. If it is omitted, false is specified.
• proc: a postprocessor object which implements the FileProcessor interface, or a function object which receives the same parameters. If it is omitted or nil, no postprocessing is performed.

Usage:

The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

Return value:

true on success, or false on failure.

db:transaction (proc, hard)

Perform entire transaction by a functor.

Parameters

• proc: the functor of operations during transaction. If the function returns true, the transaction is committed. If the function returns false or an exception is thrown, the transaction is aborted.
• hard: true for physical synchronization with the device, or false for logical synchronization with the file system. If it is omitted, false is specified.

Return value:

true on success, or false on failure.

error:__tostring ()

Get the string expression.

Return value:

the string expression.

error:code ()

Get the error code.

Return value:

the error code.

error:message ()

Get the supplement message.

Return value:

the supplement message.

error:name ()

Get the readable string of the code.

Return value:

the readable string of the code.

error:set (code, message)

Set the error information.

Parameters

• code: the error code.
• message: the supplement message.

Return value:

always nil.

fileprocessor:process (path, count, size)

Process the database file.

Parameters

• path: the path of the database file.
• count: the number of records.
• size: the size of the available region.

Return value:

true on success, or false on failure.

hash_fnv (str)

Get the hash value of a string by FNV hashing.

Parameters

• str: the string.

Return value:

the hash value.

hash_murmur (str)

Get the hash value of a string by MurMur hashing.

Parameters

• str: the string.

Return value:

the hash value.

levdist (a, b, utf)

Calculate the levenshtein distance of two strings.

Parameters

• a: one string.
• b: the other string.
• utf: flag to treat keys as UTF-8 strings. If it is omitted, false is specified.

Return value:

the levenshtein distance.

mapdump (src)

Serialize a map into a string.

Parameters

• src: the source table.

Return value:

the result string.

mapload (src)

Deserialize a string into a map.

Parameters

• src: the source string.

Return value:

the result map.

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.

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.

sleep (sec)

Suspend execution of the current thread.

Parameters

• sec: the interval of the suspension in seconds. If it is omitted, the processor is yielded from the current thread.

split (str, delims)

Split a string into substrings.

Parameters

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

Return value:

an array of substrings.

strbwm (str, pattern)

Perform backward matching without evaluating any meta character.

Parameters

• str: the source string.
• pattern: the matching pattern.

Return value:

true if they matches, or false if not.

strfwm (str, pattern)

Perform forward matching without evaluating any meta character.

Parameters

• str: the source string.
• pattern: the matching pattern.

Return value:

true if they matches, or false if not.

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 omitted, 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.

time ()

Get the time of day in seconds.

Return value:

the time of day in seconds. The accuracy is in microseconds.

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 the pack function.
• str: the binary string.

Return value:

the deserialized array.

visitor:visit_after ()

Postprocess the main operations.

visitor:visit_before ()

Preprocess the main operations.

visitor:visit_empty (key)

Visit a empty record space.

Parameters

• key: the key.

Return value:

If it is a string, the value is replaced by the content. If it is Visitor.NOP or Visitor.REMOVE, nothing is modified.

visitor:visit_full (key, value)

Visit a record.

Parameters

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

Return value:

If it is a string, the value is replaced by the content. If it is Visitor.NOP, nothing is modified. If it is Visitor.REMOVE, the record is removed.

Tables

Cursor

Interface of cursor to indicate a record.

DB

Interface of database abstraction.
Fields

• OREADER: open mode: open as a reader
• OWRITER: open mode: open as a writer
• OCREATE: open mode: writer creating
• OTRUNCATE: open mode: writer truncating
• OAUTOTRAN: open mode: auto transaction
• OAUTOSYNC: open mode: auto synchronization
• ONOLOCK: open mode: open without locking
• OTRYLOCK: open mode: lock without blocking
• ONOREPAIR: open mode: open without auto repair
• MSET: merge mode: overwrite the existing value
• MADD: merge mode: keep the existing value
• MREPLACE: merge mode: modify the existing record only
• MAPPEND: merge mode: append the new value
• XNOLOCK: mapreduce option: avoid locking against update operations
• XNOCOMP: mapreduce option: avoid compression of temporary databases

Error

Error data.
Fields

• SUCCESS: error code: success
• NOIMPL: error code: not implemented
• INVALID: error code: invalid operation
• NOREPOS: error code: no repository
• NOPERM: error code: no permission
• BROKEN: error code: broken file
• DUPREC: error code: record duplication
• NOREC: error code: no record
• LOGIC: error code: logical inconsistency
• SYSTEM: error code: system error
• MISC: error code: miscellaneous error

FileProcessor

Interface to process the database file.

Visitor

Interface to access a record.
Fields

• NOP: magic data: no operation
• REMOVE: magic data: remove the record

kc

Module object returned by the "require" expression.
Fields

• VERSION: the version information