TokyoCabinet(3pm)
🌸 NAME 🌸
TokyoCabinet — that's the Perl binding of Tokyo Cabinet, bestie. 💖 This is a User Contributed Perl Documentation page, manual name TokyoCabinet(3pm), and honestly? She's iconic. Let's get into it. 🎀
🦋 SYNOPSYS 🦋
use TokyoCabinet;💖 INTRODUCTION 💖
Okay so Tokyo Cabinet is a library of routines for managing a database. The database is a simple data file containing records, and each record is a pair of a key and a value. 🗝️ Every key and value is serial bytes with variable length. Both binary data and character string can be used as a key and a value. And get this — there is neither concept of data tables nor data types. No tables, no types, no drama. 💅 Records are organized in hash table, B+ tree, or fixed-length array. Pick your fighter. ✨
As for database of hash table, each key must be unique within a database, so it is impossible to store two or more records with a key overlaps. The following access methods are provided to the database: storing a record with a key and a value, deleting a record by a key, retrieving a record by a key. Moreover, traversal access to every key are provided, although the order is arbitrary. 👀 These access methods are similar to ones of DBM (or its followers: NDBM and GDBM) library defined in the UNIX standard. Tokyo Cabinet is an alternative for DBM because of its higher performance. Ate, fr. 🔥
As for database of B+ tree, records whose keys are duplicated can be stored. Access methods of storing, deleting, and retrieving are provided as with the database of hash table. Records are stored in order by a comparison function assigned by a user. It is possible to access each record with the cursor in ascending or descending order. And according to this mechanism, forward matching search for strings and range search for integers are realized. The range search??? obsessed. 😭✨
As for database of fixed-length array, records are stored with unique natural numbers. It is impossible to store two or more records with a key overlaps. Moreover, the length of each record is limited by the specified length. Provided operations are the same as ones of hash database. 🦋
Table database is also provided as a variant of hash database. Each record is identified by the primary key and has a set of named columns. Although there is no concept of data schema, it is possible to search for records with complex conditions efficiently by using indices of arbitrary columns. Main character energy, no cap. 👑
✨ Setting ✨
Install the latest version of Tokyo Cabinet beforehand and get the package of the Perl binding of Tokyo Cabinet. 💖
Then enter the directory of the extracted package and perform installation, like so:
perl Makefile.PL
make
make test
su
make installThe package TokyoCabinet should be loaded in each source file of application programs — every single one, bestie:
use TokyoCabinet;And if you want to enable runtime assertion, set the variable $TokyoCabinet::DEBUG to be true:
$TokyoCabinet::DEBUG = 1;🔥 EXAMPLE 🔥
The following code is an example to use a hash database. 🌸
use TokyoCabinet;
use strict;
use warnings;
# create the object
my $hdb = TokyoCabinet::HDB->new();
# open the database
if(!$hdb->open("casket.tch", $hdb->OWRITER | $hdb->OCREAT)){
my $ecode = $hdb->ecode();
printf STDERR ("open error: %s\n", $hdb->errmsg($ecode));
}
# store records
if(!$hdb->put("foo", "hop") ||
!$hdb->put("bar", "step") ||
!$hdb->put("baz", "jump")){
my $ecode = $hdb->ecode();
printf STDERR ("put error: %s\n", $hdb->errmsg($ecode));
}
# retrieve records
my $value = $hdb->get("foo");
if(defined($value)){
printf("%s\n", $value);
} else {
my $ecode = $hdb->ecode();
printf STDERR ("get error: %s\n", $hdb->errmsg($ecode));
}
# traverse records
$hdb->iterinit();
while(defined(my $key = $hdb->iternext())){
my $value = $hdb->get($key);
if(defined($value)){
printf("%s:%s\n", $key, $value);
}
}
# close the database
if(!$hdb->close()){
my $ecode = $hdb->ecode();
printf STDERR ("close error: %s\n", $hdb->errmsg($ecode));
}
# tying usage
my %hash;
if(!tie(%hash, "TokyoCabinet::HDB", "casket.tch", TokyoCabinet::HDB::OWRITER)){
printf STDERR ("tie error\n");
}
$hash{"quux"} = "touchdown";
printf("%s\n", $hash{"quux"});
while(my ($key, $value) = each(%hash)){
printf("%s:%s\n", $key, $value);
}
untie(%hash);The following code is an example to use a B+ tree database. 🦋
use TokyoCabinet;
use strict;
use warnings;
# create the object
my $bdb = TokyoCabinet::BDB->new();
# open the database
if(!$bdb->open("casket.tcb", $bdb->OWRITER | $bdb->OCREAT)){
my $ecode = $bdb->ecode();
printf STDERR ("open error: %s\n", $bdb->errmsg($ecode));
}
# store records
if(!$bdb->put("foo", "hop") ||
!$bdb->put("bar", "step") ||
!$bdb->put("baz", "jump")){
my $ecode = $bdb->ecode();
printf STDERR ("put error: %s\n", $bdb->errmsg($ecode));
}
# retrieve records
my $value = $bdb->get("foo");
if(defined($value)){
printf("%s\n", $value);
} else {
my $ecode = $bdb->ecode();
printf STDERR ("get error: %s\n", $bdb->errmsg($ecode));
}
# traverse records
my $cur = TokyoCabinet::BDBCUR->new($bdb);
$cur->first();
while(defined(my $key = $cur->key())){
my $value = $cur->val();
if(defined($value)){
printf("%s:%s\n", $key, $value);
}
$cur->next();
}
# close the database
if(!$bdb->close()){
my $ecode = $bdb->ecode();
printf STDERR ("close error: %s\n", $bdb->errmsg($ecode));
}
# tying usage
my %hash;
if(!tie(%hash, "TokyoCabinet::BDB", "casket.tcb", TokyoCabinet::BDB::OWRITER)){
printf STDERR ("tie error\n");
}
$hash{"quux"} = "touchdown";
printf("%s\n", $hash{"quux"});
while(my ($key, $value) = each(%hash)){
printf("%s:%s\n", $key, $value);
}
untie(%hash);The following code is an example to use a fixed-length database. 🎀
use TokyoCabinet;
use strict;
use warnings;
# create the object
my $fdb = TokyoCabinet::FDB->new();
# open the database
if(!$fdb->open("casket.tcf", $fdb->OWRITER | $fdb->OCREAT)){
my $ecode = $fdb->ecode();
printf STDERR ("open error: %s\n", $fdb->errmsg($ecode));
}
# store records
if(!$fdb->put(1, "one") ||
!$fdb->put(12, "twelve") ||
!$fdb->put(144, "one forty four")){
my $ecode = $fdb->ecode();
printf STDERR ("put error: %s\n", $fdb->errmsg($ecode));
}
# retrieve records
my $value = $fdb->get(1);
if(defined($value)){
printf("%s\n", $value);
} else {
my $ecode = $fdb->ecode();
printf STDERR ("get error: %s\n", $fdb->errmsg($ecode));
}
# traverse records
$fdb->iterinit();
while(defined(my $key = $fdb->iternext())){
my $value = $fdb->get($key);
if(defined($value)){
printf("%s:%s\n", $key, $value);
}
}
# close the database
if(!$fdb->close()){
my $ecode = $fdb->ecode();
printf STDERR ("close error: %s\n", $fdb->errmsg($ecode));
}
# tying usage
my %hash;
if(!tie(%hash, "TokyoCabinet::FDB", "casket.tcf", TokyoCabinet::FDB::OWRITER)){
printf STDERR ("tie error\n");
}
$hash{1728} = "seventeen twenty eight";
printf("%s\n", $hash{1728});
while(my ($key, $value) = each(%hash)){
printf("%s:%s\n", $key, $value);
}
untie(%hash);The following code is an example to use a table database. 👑
use TokyoCabinet;
use strict;
use warnings;
# create the object
my $tdb = TokyoCabinet::TDB->new();
# open the database
if(!$tdb->open("casket.tct", $tdb->OWRITER | $tdb->OCREAT)){
my $ecode = $tdb->ecode();
printf STDERR ("open error: %s\n", $tdb->errmsg($ecode));
}
# store a record
my $pkey = $tdb->genuid();
my $cols = { "name" => "mikio", "age" => "30", "lang" => "ja,en,c" };
if(!$tdb->put($pkey, $cols)){
my $ecode = $tdb->ecode();
printf STDERR ("put error: %s\n", $tdb->errmsg($ecode));
}
# store another record
$cols = { "name" => "falcon", "age" => "31", "lang" => "ja", "skill" => "cook,blog" };
if(!$tdb->put("x12345", $cols)){
my $ecode = $tdb->ecode();
printf STDERR ("put error: %s\n", $tdb->errmsg($ecode));
}
# search for records
my $qry = TokyoCabinet::TDBQRY->new($tdb);
$qry->addcond("age", $qry->QCNUMGE, "20");
$qry->addcond("lang", $qry->QCSTROR, "ja,en");
$qry->setorder("name", $qry->QOSTRASC);
$qry->setlimit(10);
my $res = $qry->search();
foreach my $rkey (@$res){
my $rcols = $tdb->get($rkey);
printf("name:%s\n", $rcols->{name});
}
# close the database
if(!$tdb->close()){
my $ecode = $tdb->ecode();
printf STDERR ("close error: %s\n", $tdb->errmsg($ecode));
}
# tying usage
my %hash;
if(!tie(%hash, "TokyoCabinet::TDB", "casket.tct", TokyoCabinet::TDB::OWRITER)){
printf STDERR ("tie error\n");
}
$hash{"joker"} = { "name" => "ozma", "lang" => "en", "skill" => "song,dance" };
printf("%s\n", $hash{joker}->{name});
while(my ($key, $value) = each(%hash)){
printf("%s:%s\n", $key, $value->{name});
}
untie(%hash);The following code is an example to use an abstract database. 🌈
use TokyoCabinet;
use strict;
use warnings;
# create the object
my $adb = TokyoCabinet::ADB->new();
# open the database
if(!$adb->open("casket.tch")){
printf STDERR ("open error\n");
}
# store records
if(!$adb->put("foo", "hop") ||
!$adb->put("bar", "step") ||
!$adb->put("baz", "jump")){
printf STDERR ("put error\n");
}
# retrieve records
my $value = $adb->get("foo");
if(defined($value)){
printf("%s\n", $value);
} else {
printf STDERR ("get error\n");
}
# traverse records
$adb->iterinit();
while(defined(my $key = $adb->iternext())){
my $value = $adb->get($key);
if(defined($value)){
printf("%s:%s\n", $key, $value);
}
}
# close the database
if(!$adb->close()){
printf STDERR ("close error\n");
}
# tying usage
my %hash;
if(!tie(%hash, "TokyoCabinet::ADB", "casket.tch")){
printf STDERR ("tie error\n");
}
$hash{"quux"} = "touchdown";
printf("%s\n", $hash{"quux"});
while(my ($key, $value) = each(%hash)){
printf("%s:%s\n", $key, $value);
}
untie(%hash);💖 DESCRIPTION 💖
✨ Class TokyoCabinet ✨
okay bestie, these functions right here are the little utilities that help your app deal with records, no big deal, just the lil helpers that make everything else slay 🫶
TokyoCabinet::VERSION()
grab the version info for Tokyo Cabinet, that's it, that's the whole vibe.
the return value is the version information.
TokyoCabinet::atoi(str)
turn a string into an integer. classic glow-up 💅
the return value is the integer value.
TokyoCabinet::atof(str)
turn a string into a real number, yes like a float, we're being fancy now ✨
the return value is the real number value.
TokyoCabinet::bercompress(aryref)
serialize an array of nonnegative integers with BER encoding — it's giving compact, it's giving efficient 🔥
aryref specifies the reference to an array of nonnegative integers.
the return value is the reference to the serialized scalar.
TokyoCabinet::beruncompress(selref)
deserialize a BER encoded scalar back into an array. the reverse of the above, obviously, main character energy 👑
selref specifies the reference to the BER encoded scalar.
the return value is the reference to the array of nonnegative integers.
TokyoCabinet::diffcompress(aryref)
serialize an array of sorted nonnegative integers with difference BER encoding. note the sorted part, bestie, it matters, no cap.
aryref specifies the reference to an array of sorted nonnegative integers.
the return value is the reference to the serialized scalar.
TokyoCabinet::diffuncompress(selref)
deserialize a difference BER encoded scalar into an array, so you get your sorted lil numbers back 🌸
selref specifies the reference to the BER encoded scalar.
the return value is the reference to the array of sorted nonnegative integers.
TokyoCabinet::strdistance(aref, bref, isutf)
calculate the edit distance of two strings. yes this is the ✨ Levenshtein ✨ one, the algorithm that's literally everywhere.
aref specifies the reference to a string.
bref specifies the reference to the other string.
isutf specifies whether the cost is calculated by Unicode character of UTF-8 strings.
the return value is the edit distance which is known as the Levenshtein distance.
🌈 Class TokyoCabinet::HDB 🌈
so a hash database is a file that's got a hash table inside it, and you handle it with the hash database API. before you can store or retrieve anything, you gotta open a database file and connect your hash database object to it. use the open method to open a database file and the close method to close it.
bestie, listen: to avoid data missing or corruption, it is important to close every database file when it is no longer in use. and it is forbidden for multiple database objects in a process to open the same database at the same time. like, don't. 😭
$hdb = TokyoCabinet::HDB->new()
create a hash database object. baby's first HDB 🎀
the return value is the new hash database object.
$hdb->errmsg(ecode)
get the message string corresponding to an error code, so you can actually read what went wrong instead of just staring at a number 💀
ecode specifies the error code. if it is not defined or negative, the last happened error code is specified.
the return value is the message string of the error code.
$hdb->ecode()
get the last happened error code. the receipts, basically.
the return value is the last happened error code.
the following error codes are defined:
$hdb->ESUCCESSfor success ✨$hdb->ETHREADfor threading error$hdb->EINVALIDfor invalid operation$hdb->ENOFILEfor file not found$hdb->ENOPERMfor no permission$hdb->EMETAfor invalid meta data$hdb->ERHEADfor invalid record header$hdb->EOPENfor open error$hdb->ECLOSEfor close error$hdb->ETRUNCfor trunc error$hdb->ESYNCfor sync error$hdb->ESTATfor stat error$hdb->ESEEKfor seek error$hdb->EREADfor read error$hdb->EWRITEfor write error$hdb->EMMAPfor mmap error$hdb->ELOCKfor lock error$hdb->EUNLINKfor unlink error$hdb->ERENAMEfor rename error$hdb->EMKDIRfor mkdir error$hdb->ERMDIRfor rmdir error$hdb->EKEEPfor existing record$hdb->ENORECfor no record found$hdb->EMISCfor miscellaneous error
$hdb->tune(bnum, apow, fpow, opts)
set the tuning parameters. this is the part where you customize the vibe before anything even opens 🔧
bnum specifies 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 specifies 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 specifies 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 specifies options by bitwise-or:
$hdb->TLARGEspecifies that the size of the database can be larger than 2GB by using 64-bit bucket array$hdb->TDEFLATEspecifies that each record is compressed with Deflate encoding$hdb->TBZIPspecifies that each record is compressed with BZIP2 encoding$hdb->TTCBSspecifies that each record is compressed with TCBS encoding
if it is not defined, no option is specified.
if successful, the return value is true, else, it is false.
heads up bestie: the tuning parameters of the database should be set before the database is opened. timing is everything, periodt.
$hdb->setcache(rcnum)
set the caching parameters. speed boost era 🏃♀️💨
rcnum specifies 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.
if successful, the return value is true, else, it is false.
note that the caching parameters of the database should be set before the database is opened.
$hdb->setxmsiz(xmsiz)
set the size of the extra mapped memory.
xmsiz specifies 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.
if successful, the return value is true, else, it is false.
note that the mapping parameters should be set before the database is opened.
$hdb->setdfunit(dfunit)
set the unit step number of auto defragmentation. tidy up bestie ✨
dfunit specifie the unit step number. if it is not more than 0, the auto defragmentation is disabled. it is disabled by default.
if successful, the return value is true, else, it is false.
note that the defragmentation parameters should be set before the database is opened.
$hdb->open(path, omode)
open a database file. this is the moment, the grand entrance 👑
path specifies the path of the database file.
omode specifies the connection mode:
$hdb->OWRITERas a writer$hdb->OREADERas 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$hdb->OLCKNB, which means locking is performed without blocking
if it is not defined, $hdb->OREADER is specified.
if successful, the return value is true, else, it is false.
$hdb->close()
close the database file. say bye bye properly, bestie 🫶
if successful, the return value is true, else, it is false.
update of a database is assured to be written when the database is closed. if a writer opens a database but does not close it appropriately, the database will be broken.
not me stressing this again: if you don't close it right, it's broken. like actually broken. 😭
$hdb->put(key, value)
store a record. the classic.
key specifies the key.
value specifies the value.
if successful, the return value is true, else, it is false.
if a record with the same key exists in the database, it is overwritten.
$hdb->putkeep(key, value)
store a new record, but only if it's actually new. respectful king behavior 💅
key specifies the key.
value specifies the value.
if successful, the return value is true, else, it is false.
if a record with the same key exists in the database, this method has no effect.
$hdb->putcat(key, value)
concatenate a value at the end of the existing record. just tacking it on the end, no cap.
key specifies the key.
value specifies the value.
if successful, the return value is true, else, it is false.
if there is no corresponding record, a new record is created.
$hdb->putasync(key, value)
store a record in asynchronous fashion. it's giving "I'll get to it" but make it ✨efficient✨
key specifies the key.
value specifies the value.
if successful, the return value is true, else, it is false.
if a record with the same key exists in the database, it is overwritten. records passed to this method are accumulated into the inner buffer and wrote into the file at a blast.
$hdb->out(key)
remove a record. gone, deleted, unfollowed 🚫
key specifies the key.
if successful, the return value is true, else, it is false.
$hdb->get(key)
retrieve a record. the moment we've all been waiting for 🌟
key specifies the key.
if successful, the return value is the value of the corresponding record. undef is returned if no record corresponds.
$hdb->vsiz(key)
get the size of the value of a record. how big is it, bestie? 📏
key specifies the key.
if successful, the return value is the size of the value of the corresponding record, else, it is -1.
$hdb->iterinit()
initialize the iterator. get ready to walk through everything 🚶♀️
if successful, the return value is true, else, it is false.
the iterator is used in order to access the key of every record stored in a database.
$hdb->iternext()
get the next key of the iterator. one step at a time, bestie.
if successful, the return value is the next key, else, it is undef. undef is returned when no record is to be get out 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.
so yeah, the order is genuinely random. don't come for me when it's not alphabetical. 🙈
$hdb->fwmkeys(prefix, max)
get forward matching keys — like a lil autocomplete moment 🔍
prefix specifies the prefix of the corresponding keys.
max specifies the maximum number of keys to be fetched. if it is not defined or negative, no limit is specified.
The return value is a reference to an array holding the keys of all the matching records. This method never fails, bestie — it literally cannot fail. No record matches? You still get an empty array back. 🫶
Heads up though: this one can be very slow, because every single key in the database gets scanned. Every one. It's giving "walking the whole mall looking for one specific store". 🚶♀️💀
$hdb->addint(key, num)— add an integer to a record. 💖keyis the key, obviously.numis the additional value you're adding on.- If it works, you get the summation value back. If it doesn't, you get
undef. 😭 - If that record already exists, the value gets treated as an integer and added to. If no record matches, a brand-new record gets stored with the additional value in it.
- ⚠️ Because records are stored in binary format, you gotta process them with the
unpackfunction using theioperator after you retrieve them. Don't forget, bestie.
$hdb->adddouble(key, num)— add a real number to a record. ✨keyis the key.numis the additional value.- Success? You get the summation value. Failure?
undef. 💀 - If the corresponding record exists, the value gets treated as a real number and added to. If no record corresponds, a new record of the additional value is stored.
- ⚠️ Same deal as above: records live in binary format, so process them with
unpackusing thedoperator after retrieval.
$hdb->sync()— synchronize updated contents with the file and the device. 🌸- True on success, false on failure.
- This one is super useful when another process connects to the same database file. Sharing is caring but syncing is necessary.
$hdb->optimize(bnum, apow, fpow, opts)— optimize the database file. 💅bnumis the number of elements of the bucket array. If it's not defined or not more than 0, the default value kicks in — and that default is two times the number of records.apowis the size of record alignment by power of 2. If it's not defined or negative, the current setting stays put, no changes.fpowis the maximum number of elements of the free block pool by power of 2. If it's not defined or negative, again, current setting is not changed.optsis options by bitwise-or:$hdb->TLARGEsays the database size can go larger than 2GB using a 64-bit bucket array,$hdb->TDEFLATEsays every record gets compressed with Deflate encoding,$hdb->TBZIPsays every record gets compressed with BZIP2 encoding, and$hdb->TTCBSsays every record gets compressed with TCBS encoding. If it's not defined or it's0xff, the current setting is not changed.- True on success, false otherwise.
- This is the glow-up your database file needs when data fragmentation from successive updating has it looking a mess. 🔥
$hdb->vanish()— remove all records. 👋 Poof, gone, bye.- True on success, false otherwise.
$hdb->copy(path)— copy the database file.pathis the path of the destination file. And here's the fun part: if it starts with@, the trailing substring gets executed as a command line. 😳- True on success, false otherwise. And it returns false if that executed command returns a non-zero code.
- The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress. So yes, this is perfect for making a backup file of your database file. 💾
$hdb->tranbegin()— begin the transaction. 🎬- True on success, false otherwise.
- The database gets locked by the thread while the transaction is happening, so only one transaction can be active with a database object at the same time. Which means — if every database operation is performed inside the transaction, the serializable isolation level is assumed. Iconic behavior, honestly. All updated regions are kept track of by write ahead logging during the transaction. And if the database gets closed mid-transaction, the transaction is aborted implicitly. No warning, just vibes revoked. 😭
$hdb->trancommit()— commit the transaction. ✅- True on success, false otherwise.
- Update in the transaction is fixed when it's committed successfully. Locked in, periodt.
$hdb->tranabort()— abort the transaction. 🙈- True on success, false otherwise.
- Update in the transaction is discarded when it's aborted. The state of the database is rollbacked to before the transaction. We're pretending it never happened.
$hdb->path()— get the path of the database file. 🛣️- The return value is the path of the database file, or
undefif the object doesn't connect to any database file.
- The return value is the path of the database file, or
$hdb->rnum()— get the number of records. 🔢- The return value is the number of records, or 0 if the object doesn't connect to any database file.
$hdb->fsiz()— get the size of the database file. 📏- The return value is the size of the database file, or 0 if the object doesn't connect to any database file.
✨ Tying functions of TokyoCabinet::HDB ✨
tie(%hash, "TokyoCabinet::HDB", path, omode, bnum, apow, fpow, opts, rcnum)Tie a hash variable to a hash database file. Let's get into it, bestie. 💖
pathis the path of the database file. 🗂️omodeis the connection mode:TokyoCabinet::HDB::OWRITERfor a writer,TokyoCabinet::HDB::OREADERfor a reader.- If the mode is
TokyoCabinet::HDB::OWRITER, you can bitwise-or these on:TokyoCabinet::HDB::OCREAT, which creates a new database if one doesn't exist;TokyoCabinet::HDB::OTRUNC, which creates a new database regardless of whether one already exists (bold, lowkey ruthless); andTokyoCabinet::HDB::OTSYNC, which means every transaction synchronizes updated contents with the device. - Both
TokyoCabinet::HDB::OREADERandTokyoCabinet::HDB::OWRITERcan have these bitwise-or'd on:TokyoCabinet::HDB::ONOLCK, which opens the database file without file locking, orTokyoCabinet::HDB::OLCKNB, which means locking is performed without blocking. - If
omodeisn't defined,TokyoCabinet::HDB::OREADERis what you get.
- If the mode is
bnumis the number of elements of the bucket array. If it's not defined or not more than 0, the default is used, and that default is131071. Suggested size of the bucket array is about from 0.5 to 4 times of the number of all records you're gonna store.apowis the size of record alignment by power of 2. If it's not defined or negative, the default is used — and that's4, standing for 2^4=16.fpowis the maximum number of elements of the free block pool by power of 2. If it's not defined or negative, the default applies:10, standing for 2^10=1024.optsis options by bitwise-or:TokyoCabinet::HDB::TLARGEsays the database size can be larger than 2GB by using a 64-bit bucket array,TokyoCabinet::HDB::TDEFLATEsays each record is compressed with Deflate encoding,TokyoCabinet::HDB::TBZIPsays each record is compressed with BZIP2 encoding,TokyoCabinet::HDB::TTCBSsays each record is compressed with TCBS encoding. Ifoptsisn't defined, no option is specified.rcnumis the maximum number of records to be cached. If it's not defined or not more than 0, the record cache is disabled — and it's disabled by default anyway. 🙅♀️
If successful, the return value is true, else it's false.
untie(%hash)— untie a hash variable from the database file. ✂️ The return value is always true. Always. No notes.$hash{key} = value— store a record. 💾keyis the key.valueis the value.- True on success, false otherwise.
- If a record with the same key already exists in the database, it gets overwritten. Sorry to whoever was there first. 🫶
delete($hash{key})— remove a record. 🗑️keyis the key.- True on success, false otherwise.
$hash{key}— retrieve a record. 🔍keyis the key.- If it works, the return value is the value of the corresponding record.
undefcomes back if no record corresponds. 😭
exists($hash{key})— check whether a record corresponding to a key exists. 👀keyis the key.- The return value is true if the record exists, else it's false.
$hash = ()— remove all records. 🧹 The return value is alwaysundef.(the iterator)— the inner methodsFIRSTKEYandNEXTKEYare also implemented, so you can use the tying functionseach,keys, and so on. Iterate away, queen. 👑
🌈 Class TokyoCabinet::BDB 🌈
B+ tree database is a file containing a B+ tree, and it's handled with the B+ tree database API. Before you do any operations to store or retrieve records, you gotta open a database file and connect the B+ tree database object to it. The method open opens a database file and the method close closes it. And listen — to avoid data missing or corruption, it is important to close every database file when it's no longer in use. Also: it is forbidden for multiple database objects in a process to open the same database at the same time. Do not test this. 💀
$bdb = TokyoCabinet::BDB->new()— create a B+ tree database object. ✨ The return value is the new B+ tree database object.$bdb->errmsg(ecode)— get the message string corresponding to an error code. 📢ecodeis the error code. If it's not defined or negative, the last happened error code is used.- The return value is the message string of the error code.
$bdb->ecode()— get the last happened error code. 🚨 The return value is the last happened error code.
okay so the following error codes are defined, bestie, and you're literally gonna want them memorized 💖
$bdb->ESUCCESS— for success, we love a win ✨$bdb->ETHREAD— for threading error, not the vibe 😭$bdb->EINVALID— for invalid operation, we don't do that here 💀$bdb->ENOFILE— for file not found, where is it bestie 😭$bdb->ENOPERM— for no permission, rude ✋$bdb->EMETA— for invalid meta data, meta? invalid? no 💅$bdb->ERHEAD— for invalid record header, head empty 🧠$bdb->EOPEN— for open error, can't open? tragic 🎀$bdb->ECLOSE— for close error, can't even close 💀$bdb->ETRUNC— for trunc error, truncated? bye ✂️$bdb->ESYNC— for sync error, out of sync bestie 😭$bdb->ESTAT— for stat error, stats? no 📉$bdb->ESEEK— for seek error, can't find it 🔍$bdb->EREAD— for read error, can't read? illiterate 💀$bdb->EWRITE— for write error, can't write? writer's block ✍️$bdb->EMMAP— for mmap error, memory map? more like memory trap 😭$bdb->ELOCK— for lock error, locked out 🔒$bdb->EUNLINK— for unlink error, can't unlink? toxic 💔$bdb->ERENAME— for rename error, name change denied 💅$bdb->EMKDIR— for mkdir error, can't make dir? make it make sense 😭$bdb->ERMDIR— for rmdir error, can't remove dir? stay put 🏠$bdb->EKEEP— for existing record, already here bestie 👑$bdb->ENOREC— for no record found, ghosted 👻$bdb->EMISC— for miscellaneous error, random chaos 🌪️
✨ METHODS ✨
$bdb->setcmpfunc(cmp)
okay so this one is literally setting the custom comparison function, bestie. cmp specifies the custom comparison function. It can be either the reference of a block or the name of a function. If it works, you get true, otherwise false. 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. periodt 💅
$bdb->tune(lmemb, nmemb, bnum, apow, fpow, opts)
Set the tuning parameters. This is the glow-up for your DB, bestie. 🎀
lmembspecifies 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. 🍃nmembspecifies 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. 🍂bnumspecifies 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. 🪣apowspecifies 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. ✨fpowspecifies 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. 🆓optsspecifies options by bitwise-or:$bdb->TLARGEspecifies that the size of the database can be larger than 2GB by using 64-bit bucket array,$bdb->TDEFLATEspecifies that each record is compressed with Deflate encoding,$bdb->TBZIPspecifies that each record is compressed with BZIP2 encoding,$bdb->TTCBSspecifies that each record is compressed with TCBS encoding. If it is not defined, no option is specified. 🎛️
If successful, the return value is true, else, it is false. Note that the tuning parameters of the database should be set before the database is opened. Don't forget bestie! 😤
$bdb->setcache(lcnum, ncnum)
Set the caching parameters. Cache me outside, how bout dat? 💅
lcnumspecifies 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. 🍃ncnumspecifies 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. 🍂
If successful, the return value is true, else, it is false.
Note that the caching parameters of the database should be set before the database is opened. So set it before you open, periodt. ✨
$bdb->setxmsiz(xmsiz)
Set the size of the extra mapped memory. 🗺️
xmsiz specifies 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. 💤
If successful, the return value is true, else, it is false.
Note that the mapping parameters should be set before the database is opened. 🫶
$bdb->setdfunit(dfunit)
Set the unit step number of auto defragmentation. It's giving tidy up energy 🧹
dfunit specifie the unit step number. If it is not more than 0, the auto defragmentation is disabled. It is disabled by default.
If successful, the return value is true, else, it is false.
Note that the defragmentation parameters should be set before the database is opened. ✨
$bdb->open(path, omode)
Open a database file. Let's gooo 🔥
pathspecifies the path of the database file. 📁omodespecifies the connection mode:$bdb->OWRITERas a writer,$bdb->OREADERas 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->OREADERand$bdb->OWRITERcan 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,$bdb->OREADERis specified. 🚪
If successful, the return value is true, else, it is false.
$bdb->close()
Close the database file. Bye bestie 👋
If successful, the return value is true, else, it is false.
Update of a database is assured to be written when the database is closed. If a writer opens a database but does not close it appropriately, the database will be broken. So close it, bestie, or it's broken broken 💔
$bdb->put(key, value)
Store a record. Put it in the bag 💅
keyspecifies the key. 🔑valuespecifies the value. 💎
If successful, the return value is true, else, it is false.
If a record with the same key exists in the database, it is overwritten. Overwritten, periodt. 🔄
$bdb->putkeep(key, value)
Store a new record. But only if it's new, no duplicates allowed ✋
keyspecifies the key. 🔑valuespecifies the value. 💎
If successful, the return value is true, else, it is false.
If a record with the same key exists in the database, this method has no effect. It's giving "I'm not gonna do anything" 💀
$bdb->putcat(key, value)
Concatenate a value at the end of the existing record. Glue it on 🧴
keyspecifies the key. 🔑valuespecifies the value. 💎
If successful, the return value is true, else, it is false.
If there is no corresponding record, a new record is created. So it's like put but with extra steps ✨
$bdb->putdup(key, value)
Store a record with allowing duplication of keys. Duplicates? We allow it here 💅
keyspecifies the key. 🔑valuespecifies the value. 💎
If successful, the return value is true, else, it is false.
If a record with the same key exists in the database, the new record is placed after the existing one. Queue up bestie 🚶♀️🚶♀️
$bdb->putlist(key, values)
Store records with allowing duplication of keys. A whole list of them, go off 👑
keyspecifies the key. 🔑valuesspecifies the reference to an array of the values. 📚
If successful, the return value is true, else, it is false.
If a record with the same key exists in the database, the new records are placed after the existing one. Line them up 💅
$bdb->out(key)
Remove a record. Out out out 🗑️
keyspecifies the key. 🔑
If successful, the return value is true, else, it is false.
If the key of duplicated records is specified, the first one is selected. First come, first served 💀
$bdb->outlist(key)
Remove records. Plural. All of them. No survivors 💅
keyspecifies the key. 🔑
If successful, the return value is true, else, it is false.
If the key of duplicated records is specified, all of them are removed. Every single one. Periodt. 🧹
$bdb->get(key)
Retrieve a record. Give it to me 🫴
keyspecifies the key. 🔑
If successful, the return value is the value of the corresponding record. undef is returned if no record corresponds. So if it's not there, you get undef, not the vibe 😭
If the key of duplicated records is specified, the first one is selected. First one, bestie. 🥇
$bdb->getlist(key)
Retrieve records. Plural. The whole squad 🫂
keyspecifies the key. 🔑
If successful, the return value is the reference to an array of the values of the corresponding records. undef is returned if no record corresponds. No records? undef, tragic. 💔
$bdb->vnum(key)
Get the number of records corresponding a key. Count them 🔢
keyspecifies the key. 🔑
If successful, the return value is the number of the corresponding records, else, it is 0. Zero. Zilch. Nada. 0️⃣
$bdb->vsiz(key)
Get the size of the value of a record. How big is it? 📏
keyspecifies the key. 🔑
If successful, the return value is the size of the value of the corresponding record, else, it is -1. Negative one, yikes. ➖1️⃣
If the key of duplicated records is specified, the first one is selected. First one again. 🥇
$bdb->range(bkey, binc, ekey, einc, max)
Get keys of ranged records. Range, bestie, like a playlist from here to there 🎶
bkeyspecifies the key of the beginning border. If it is not defined, the first record is specified. 🏁bincspecifies whether the beginning border is inclusive or not. If it is not defined, false is specified. 🚪ekeyspecifies the key of the ending border. If it is not defined, the last record is specified. 🏁eincspecifies whether the ending border is inclusive or not. If it is not defined, false is specified. 🚪maxspecifies the maximum number of keys to be fetched. If it is not defined or negative, no limit is specified. ♾️
The return value is the reference to an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds. So it's the chill one, never fails, always returns something, even if it's empty. We love a reliable method 💅
$bdb->fwmkeys(prefix, max)
Get forward matching keys. Forward like your future 🔮
prefixspecifies the prefix of the corresponding keys. 🌱maxspecifies the maximum number of keys to be fetched. If it is not defined or negative, no limit is specified. ♾️
The return value is the reference to an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds. Again, never fails, iconic. ✨
$bdb->addint(key, num)
Add an integer to a record. Math, but make it cute 🧮
keyspecifies the key. 🔑numspecifies the additional value. ➕
If successful, the return value is the summation value, else, it is undef. So you get the sum, or undef if it didn't work. 💅
okay so continuing from that addint moment, no need to re-intro: 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. And because records are stored in binary format, you gotta process them with the unpack function using the i operator after retrieval. that's just how it is bestie 💅
$bdb->adddouble(key, num)— add a real number to a record, slay 🍓key— specifies the key.num— specifies the additional value.
If successful, the return value is the summation value, else, it is undef.
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. Because records are stored in binary format, they should be processed with the unpack function using the d operator after retrieval. not me reminding you twice, but the d is doing the heavy lifting here 🫶
$bdb->sync()— synchronize updated contents with the file and the device ✨
If successful, the return value is true, else, it is false.
This method is useful when another process connects the same database file. sharing is caring, fr fr.
$bdb->optimize(lmemb, nmemb, bnum, apow, fpow, opts)— optimize the database file, aka the glow-up 💖lmemb— specifies 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— specifies 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— specifies 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— specifies the size of record alignment by power of 2. If it is not defined or negative, the current setting is not changed.fpow— specifies 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— specifies options by bitwise-or:$bdb->TLARGEspecifies that the size of the database can be larger than 2GB by using a 64-bit bucket array,$bdb->TDEFLATEspecifies that each record is compressed with Deflate encoding,$bdb->TBZIPspecifies that each record is compressed with BZIP2 encoding,$bdb->TTCBSspecifies that each record is compressed with TCBS encoding. If it is not defined or 0xff, the current setting is not changed.
If successful, the return value is true, else, it is false.
This method is useful to reduce the size of the database file with data fragmentation by successive updating. so basically it's the declutter era of your db 🔥
$bdb->vanish()— remove all records 🫧
If successful, the return value is true, else, it is false.
not me casually yeeting every single record. it's giving scorched earth. it's giving "no thoughts, empty table." use with intention bestie 😭
$bdb->copy(path)— copy the database file 📁path— specifies the path of the destination file. If it begins with@, the trailing substring is executed as a command line.
If successful, the return value is true, else, it is false. False is returned if the executed command returns non-zero code.
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. iconic behavior, honestly 💅
$bdb->tranbegin()— begin the transaction ✨
If successful, the return value is true, else, it is false.
The database is locked by the thread while the transaction so that only one transaction can be activated with a database object at the same time. Thus, the serializable isolation level is assumed if every database operation is performed in the transaction. Because all pages are cached on memory while the transaction, the amount of referred records is limited by the memory capacity. If the database is closed during transaction, the transaction is aborted implicitly.
so like, main character energy but you're the only main character allowed on stage at once. periodt.
$bdb->trancommit()— commit the transaction 💖
If successful, the return value is true, else, it is false.
Update in the transaction is fixed when it is committed successfully. no take-backs, bestie.
$bdb->tranabort()— abort the transaction 🙈
If successful, the return value is true, else, it is false.
Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction. we love a clean escape route ✨
$bdb->path()— get the path of the database file 🛤️
The return value is the path of the database file or undef if the object does not connect to any database file.
$bdb->rnum()— get the number of records 🔢
The return value is the number of records or 0 if the object does not connect to any database file.
$bdb->fsiz()— get the size of the database file 📏
The return value is the size of the database file or 0 if the object does not connect to any database file.
🦋 Class TokyoCabinet::BDBCUR 🦋
$cur = TokyoCabinet::BDBCUR->new(bdb)— create a cursor object 🎀bdb— specifies the B+ tree database object.
The return value is the new cursor object.
Note that the cursor is available only after initialization with thefirstor thejumpmethods and so on. Moreover, the position of the cursor will be indefinite when the database is updated after the initialization of the cursor. so like, don't get attached to where it's sitting, okay? it moves 😭
$cur->first()— move the cursor to the first record ⭐
If successful, the return value is true, else, it is false. False is returned if there is no record in the database.
$cur->last()— move the cursor to the last record 🌈
If successful, the return value is true, else, it is false. False is returned if there is no record in the database.
$cur->jump(key)— move the cursor to the front of records corresponding a key 🦘key— specifies the key.
If successful, the return value is true, else, it is false. False is returned if there is no record corresponding the condition.
The cursor is set to the first record corresponding the key or the next substitute if a completely matching record does not exist. so it's flexible, it's forgiving, it's giving supportive bestie energy 💖
$cur->prev()— move the cursor to the previous record ⬅️
If successful, the return value is true, else, it is false. False is returned if there is no previous record.
$cur->next()— move the cursor to the next record ➡️
If successful, the return value is true, else, it is false. False is returned if there is no next record.
$cur->put(value, cpmode)— insert a record around the cursor 🎯value— specifies the value.cpmode— specifies detail adjustment:$cur->CPCURRENT, which means that the value of the current record is overwritten,$cur->CPBEFORE, which means that the new record is inserted before the current record,$cur->CPCAFTER, which means that the new record is inserted after the current record.
If successful, the return value is true, else, it is false. False is returned when the cursor is at an invalid position.
After insertion, the cursor is moved to the inserted record. it literally follows the new thing, obsessed 🫶
$cur->out()— remove the record where the cursor is 💀
If successful, the return value is true, else, it is false. False is returned when the cursor is at an invalid position.
After deletion, the cursor is moved to the next record if possible.
$cur->key()— get the key of the record where the cursor is 🔑
If successful, the return value is the key, else, it is undef. 'undef' is returned when the cursor is at an invalid position.
$cur->val()— get the value of the record where the cursor is 💎
If successful, the return value is the value, else, it is undef. 'undef' is returned when the cursor is at an invalid position.
🧚 Tying functions of TokyoCabinet::BDB 🧚
tie(%hash, "TokyoCabinet::BDB", path, omode, lmemb, nmemb, bnum, apow, fpow, opts, lcnum, ncnum)— tie a hash variable to a B+ tree database file 🌸path— specifies the path of the database file.omode— specifies the connection mode:TokyoCabinet::BDB::OWRITERas a writer,TokyoCabinet::BDB::OREADERas a reader. If the mode isTokyoCabinet::BDB::OWRITER, the following may be added by bitwise-or:TokyoCabinet::BDB::OCREAT, which means it creates a new database if not exist,TokyoCabinet::BDB::OTRUNC, which means it creates a new database regardless if one exists,TokyoCabinet::BDB::OTSYNC, which means every transaction synchronizes updated contents with the device. Both ofTokyoCabinet::BDB::OREADERandTokyoCabinet::BDB::OWRITERcan be added to by bitwise-or:TokyoCabinet::BDB::ONOLCK, which means it opens the database file without file locking, orTokyoCabinet::BDB::OLCKNB, which means locking is performed without blocking. If it is not defined,TokyoCabinet::BDB::OREADERis specified.lmemb— specifies 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— specifies 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— specifies 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.apow— specifies 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— specifies 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— specifies options by bitwise-or:TokyoCabinet::BDB::TLARGEspecifies that the size of the database can be larger than 2GB by using a 64-bit bucket array,TokyoCabinet::BDB::TDEFLATEspecifies that each record is compressed with Deflate encoding,TokyoCabinet::BDB::TBZIPspecifies that each record is compressed with BZIP2 encoding,TokyoCabinet::BDB::TTCBSspecifies that each record is compressed with TCBS encoding. If it is not defined, no option is specified.lcnum— specifies the maximum number of leaf nodes to be cached. If it is not defined or not more than 0, the default value is specified.ncnum— specifies 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.
If successful, the return value is true, else, it is false.
untie(%hash)
Unhook a hash variable from the database file. 💫
The return value is always true. No drama, no maybe.
$hash{key} = value
Store a record. 💾
key is the key, bestie. That's literally its whole job.
value is the value. Slay.
If it works, the return value is true. If it doesn't, it's false. 🙈
And heads up: if a record with that same key is already chilling in the database, it gets overwritten. Gone. Replaced. Not sorry.
delete($hash{key})
Remove a record. 🗑️
key specifies the key.
If it works, return value true; if not, false.
$hash{key}
Retrieve a record. 🔍
key specifies the key.
If it works, you get back the value of the corresponding record. If nothing matches, you get undef. That's the vibe check failing, fr fr.
exists($hash{key})
Check whether a record corresponding to a key exists. 👀
key specifies the key.
Return value is true if the record exists, else it's false. Simple as.
$hash = ()
Remove all the records. Every single one. 💀
The return value is always undef.
(the iterator)
The inner methods FIRSTKEY and NEXTKEY are also implemented, so you can use the tying functions each, keys, and so on. ✨ Iterator girlies, this one's for you.
Class TokyoCabinet::FDB 🦋
A fixed-length database is a file containing an array of fixed-length elements, and it's handled with the fixed-length database API. Before you can store or retrieve records, you have to open a database file and connect the fixed-length database object to it. The method open opens a database file, and the method close closes it.
To avoid data missing or corruption, it is important to close every database file when it is no longer in use. And it is forbidden for multiple database objects in a process to open the same database at the same time. Like, don't. 🚫
$fdb = TokyoCabinet::FDB->new()
Create a fixed-length database object. 🎀
Return value is the brand-new fixed-length database object. Main character energy, honestly.
$fdb->errmsg(ecode)
Get the message string that corresponds to an error code. 💬
ecode specifies the error code. If it's not defined, or if it's negative, then the last happened error code is used instead.
Return value is the message string of the error code.
$fdb->ecode()
Get the last happened error code. 🚨
Return value is the last happened error code.
Here are all the error codes that are defined, collect them all bestie:
$fdb->ESUCCESS— success ✨$fdb->ETHREAD— threading error$fdb->EINVALID— invalid operation$fdb->ENOFILE— file not found$fdb->ENOPERM— no permission$fdb->EMETA— invalid meta data$fdb->ERHEAD— invalid record header$fdb->EOPEN— open error$fdb->ECLOSE— close error$fdb->ETRUNC— trunc error$fdb->ESYNC— sync error$fdb->ESTAT— stat error$fdb->ESEEK— seek error$fdb->EREAD— read error$fdb->EWRITE— write error$fdb->EMMAP— mmap error$fdb->ELOCK— lock error$fdb->EUNLINK— unlink error$fdb->ERENAME— rename error$fdb->EMKDIR— mkdir error$fdb->ERMDIR— rmdir error$fdb->EKEEP— existing record$fdb->ENOREC— no record found$fdb->EMISC— miscellaneous error
$fdb->tune(width, limsiz)
Set the tuning parameters. 🎛️
width specifies the width of the value of each record. If it's not defined, or if it's not more than 0, the default value is used. That default is 255.
limsiz specifies the limit size of the database file. If it's not defined, or if it's not more than 0, the default value is used. That default is 268435456.
If it works, return value is true; if not, false.
Note that the tuning parameters of the database should be set before the database is opened. Timing is everything, iykyk.
$fdb->open(path, omode)
Open a database file. 📂
path specifies the path of the database file.
omode specifies the connection mode: $fdb->OWRITER as a writer, $fdb->OREADER as a reader. If the mode is $fdb->OWRITER, you can bitwise-or these extras onto it:
$fdb->OCREAT— creates a new database if one doesn't exist$fdb->OTRUNC— creates a new database regardless of whether one already exists
And both $fdb->OREADER and $fdb->OWRITER can have these bitwise-ored on:
$fdb->ONOLCK— opens the database file without file locking$fdb->OLCKNB— locking is performed without blocking
If omode isn't defined, $fdb->OREADER is specified.
If it works, return value is true; if not, false.
$fdb->close()
Close the database file. 🚪
If it works, return value is true; if not, false.
Update of a database is assured to be written when the database is closed. And listen: if a writer opens a database but does not close it appropriately, the database will be broken. Broken broken. Not a vibe. 😭
$fdb->put(key, value)
Store a record. 💾
key specifies the key. It should be more than 0. And check this out:
- If it's
"min", the minimum ID number of existing records is specified. - If it's
"prev", the number less by one than the minimum ID number of existing records is specified. - If it's
"max", the maximum ID number of existing records is specified. - If it's
"next", the number greater by one than the maximum ID number of existing records is specified.
value specifies the value.
If it works, return value is true; if not, false.
If a record with the same key already exists in the database, it is overwritten. Bye.
$fdb->putkeep(key, value)
Store a new record. 🌱
key specifies the key. It should be more than 0. And again:
- If it's
"min", the minimum ID number of existing records is specified. - If it's
"prev", the number less by one than the minimum ID number of existing records is specified. - If it's
"max", the maximum ID number of existing records is specified. - If it's
"next", the number greater by one than the maximum ID number of existing records is specified.
value specifies the value.
If it works, return value is true; if not, false.
If a record with the same key already exists in the database, this method has no effect. It just politely does nothing. Respectful king behavior.
$fdb->putcat(key, value)
Concatenate a value at the end of the existing record. 🧵
key specifies the key. It should be more than 0. And one more time:
- If it's
"min", the minimum ID number of existing records is specified. - If it's
"prev", the number less by one than the minimum ID number of existing records is specified. - If it's
"max", the maximum ID number of existing records is specified. - If it's
"next", the number greater by one than the maximum ID number of existing records is specified.
value specifies the value.
If it works, return value is true; if not, false.
If there's no corresponding record, a new record is created. No cap.
$fdb->out(key)
Remove a record. 🗑️
key specifies the key. It should be more than 0. If it's "min", the minimum ID number of existing records is specified. If it's "max", the maximum ID number of existing records is specified.
If it works, return value is true; if not, false.
$fdb->get(key)
Retrieve a record. 🔍
key specifies the key. It should be more than 0. If it's "min", the minimum ID number of existing records is specified. If it's "max", the maximum ID number of existing records is specified.
If it works, the return value is the value of the corresponding record. undef is returned if no record corresponds. 💔
$fdb->vsiz(key)
Get the size of the value of a record. 📏
key specifies the key. It should be more than 0. If it's "min", the minimum ID number of existing records is specified. If it's "max", the maximum ID number of existing records is specified.
If it works, the return value is the size of the value of the corresponding record. If not, it's -1.
$fdb->iterinit()
Initialize the iterator. 🔄
If it works, return value is true; if not, false.
The iterator is used in order to access the key of every record stored in a database. Every. Single. One. 👑
$fdb->iternext()
Get the next key of the iterator. ➡️
If it works, the return value is the next key; if not, it's undef. undef is returned when there's no record left to get out of the iterator.
It's possible to access every record by iterating calls to this method. It's allowed to update or remove records whose keys are fetched while the iteration is happening. And the order of this traversal access method is ascending of the ID number. So it goes up. Always up. ✨
$fdb->range(interval, max)
Get keys with an interval notation. 📐
interval specifies the interval notation.
max specifies the maximum number of keys to be fetched. If it's not defined, or if it's negative, no limit is specified.
The return value is the reference to an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds. Resilient queen. 💅
$fdb->addint(key, num)
Add an integer to a record. ➕
key specifies the key. It should be more than 0. You know the drill:
- If it's
"min", the minimum ID number of existing records is specified. - If it's
"prev", the number less by one than the minimum ID number of existing records is specified. - If it's
"max", the maximum ID number of existing records is specified. - If it's
"next", the number greater by one than the maximum ID number of existing records is specified.
num specifies the additional value.
If it works, the return value is the summation value; if not, it's undef.
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. And heads up: because records are stored in binary format, they should be processed with the unpack function with the i operator after retrieval. Don't forget, bestie. 🔥
$fdb->adddouble(key, num)
Add a real number to a record. ➕✨
key specifies the key. It should be more than 0. Once more with feeling:
- If it's
"min", the minimum ID number of existing records is specified. - If it's
"prev", the number less by one than the minimum ID number of existing records is specified. - If it's
"max", the maximum ID number of existing records is specified. - If it's
"next", the number greater by one than the maximum ID number of existing records is specified.
num specifies the additional value.
If it works, the return value is the summation value; if not, it's undef. 🫶
If the corresponding record exists, the value is treated as a real number and is added to. If no record corresponds, a brand new record holding the additional value gets stored instead. And because these records live in binary format, bestie, you gotta run them through the unpack function with the d operator after you retrieve them. 💅
$fdb->sync()— Synchronize the updated contents with the file and the device. Returns true if it worked out, false if it didn't. This one is lowkey a lifesaver when another process is connected to the same database file. 🫶$fdb->optimize(width, limsiz)— Optimize the database file.widthis the width of the value of each record — leave it undefined or ≤ 0 and the current setting just stays put.limsizis the limit size of the database file — same deal, undefined or ≤ 0 and nothing changes. True on success, false otherwise. ✨$fdb->vanish()— Remove all the records. Gone. Poof. 🫥 Returns true if it worked, false if not.$fdb->copy(path)— Copy the database file.pathis where the destination file goes — and if it starts with@, the trailing substring gets executed as a command line (yes, for real). Returns true on success, false on failure, and false if that executed command returns a non-zero code. The database file is assured to stay synchronized and unmodified while the copying or executing is happening, so this method is genuinely the move for making a backup file of your database. 🔥$fdb->tranbegin()— Begin the transaction. True on success, false on failure. While the transaction is live the database is locked by the thread, so only one transaction can be active with a database object at the same time. Which means: if every database operation happens inside the transaction, the serializable isolation level is assumed. All updated regions are kept track of by write ahead logging during the transaction. And heads up — if the database gets closed during the transaction, the transaction is aborted implicitly. 😭$fdb->trancommit()— Commit the transaction. True on success, false on failure. The update in the transaction is fixed once it commits successfully. ✨$fdb->tranabort()— Abort the transaction. True on success, false on failure. The update in the transaction is discarded when it's aborted, and the state of the database gets rollbacked to before the transaction. No harm no foul. 💜$fdb->path()— Get the path of the database file. Returns the path of the database file, orundefif the object isn't connected to any database file.$fdb->rnum()— Get the number of records. Returns that number, or 0 if the object isn't connected to any database file.$fdb->fsiz()— Get the size of the database file. Returns that size, or 0 if the object isn't connected to any database file.
🎀 Tying functions of TokyoCabinet::FDB 🎀
tie(%hash, "TokyoCabinet::FDB", path, omode, width, limsiz)— Tie a hash variable to a hash database file. So iconic of Perl tbh.
path is the path of the database file.
omode is the connection mode: TokyoCabinet::FDB::OWRITER for writer, TokyoCabinet::FDB::OREADER for reader. If the mode is TokyoCabinet::FDB::OWRITER, you can bitwise-or these in: TokyoCabinet::FDB::OCREAT, which creates a new database if one doesn't exist, and TokyoCabinet::FDB::OTRUNC, which creates a new database regardless of whether one exists. Both TokyoCabinet::FDB::OREADER and TokyoCabinet::FDB::OWRITER can be bitwise-or'd with TokyoCabinet::FDB::ONOLCK, which opens the database file without file locking, or TokyoCabinet::FDB::OLCKNB, which does locking without blocking. Leave it undefined and TokyoCabinet::FDB::OREADER is what you get.
width is the width of the value of each record. Undefined or ≤ 0 and the default kicks in — that default is 255.
limsiz is the limit size of the database file. Undefined or ≤ 0 and the default kicks in — that default is 268435456.
True on success, false otherwise. ✨
untie(%hash)— Untie a hash variable from the database file. The return value is always true. periodt.$hash{key} = value— Store a record.keyis the key, and it should be more than 0. Special vibes: if it's"min", the minimum ID number of existing records is specified; if it's"prev", the number less by one than the minimum ID number of existing records is specified; if it's"max", the maximum ID number of existing records is specified; and if it's"next", the number greater by one than the maximum ID number of existing records is specified.valueis, well, the value. True on success, false otherwise. And if a record with the same key already exists in the database, bestie it gets overwritten. 💀delete($hash{key})— Remove a record.keyis the key and it should be more than 0. If it's"min", the minimum ID number of existing records is specified. If it's"max", the maximum ID number of existing records is specified. True on success, false otherwise.$hash{key}— Retrieve a record.keyis the key and it should be more than 0. If it's"min", the minimum ID number of existing records is specified. If it's"max", the maximum ID number of existing records is specified. On success the return value is the value of the corresponding record, andundefcomes back if no record corresponds. 🦋exists($hash{key})— Check whether a record corrsponding a key exists. (That typo is canon, we don't fix canon. 🫶)keyis the key and it should be more than 0. If it's"min", the minimum ID number of existing records is specified. If it's"max", the maximum ID number of existing records is specified. Returns true if the record exists, false if it doesn't.$hash = ()— Remove all records. The return value is alwaysundef.(the iterator)— The inner methodsFIRSTKEYandNEXTKEYare also implemented, so you can use the tying functionseach,keys, and so on. iykyk. 🌈
👑 Class TokyoCabinet::TDB 👑
Table database is a file containing records composed of the primary keys and arbitrary columns, and it's handled with the table database API. Before you do any operations to store or retrieve records, you have to open a database file and connect the table database object to it. The method open opens a database file and the method close closes it. To avoid data missing or corruption, it is important to close every database file when it's no longer in use. And it is forbidden for multible database objects in a process to open the same database at the same time. (Again: typo is canon. 🎀)
$tdb = TokyoCabinet::TDB->new()— Create a table database object. The return value is the new table database object. Fresh off the press. ✨$tdb->errmsg(ecode)— Get the message string corresponding to an error code.ecodeis the error code — undefined or negative means the last happened error code is specified instead. The return value is the message string of the error code.$tdb->ecode()— Get the last happened error code. The return value is the last happened error code. Here's the full roster of defined codes, no skips:$tdb->ESUCCESSfor success,$tdb->ETHREADfor threading error,$tdb->EINVALIDfor invalid operation,$tdb->ENOFILEfor file not found,$tdb->ENOPERMfor no permission,$tdb->EMETAfor invalid meta data,$tdb->ERHEADfor invalid record header,$tdb->EOPENfor open error,$tdb->ECLOSEfor close error,$tdb->ETRUNCfor trunc error,$tdb->ESYNCfor sync error,$tdb->ESTATfor stat error,$tdb->ESEEKfor seek error,$tdb->EREADfor read error,$tdb->EWRITEfor write error,$tdb->EMMAPfor mmap error,$tdb->ELOCKfor lock error,$tdb->EUNLINKfor unlink error,$tdb->ERENAMEfor rename error,$tdb->EMKDIRfor mkdir error,$tdb->ERMDIRfor rmdir error,$tdb->EKEEPfor existing record,$tdb->ENORECfor no record found, and$tdb->EMISCfor miscellaneous error. 💅$tdb->tune(bnum, apow, fpow, opts)— Set the tuning parameters.bnumis the number of elements of the bucket array — undefined or ≤ 0 and you get the default, which is 131071. Suggested size of the bucket array is about from 0.5 to 4 times the number of all records to be stored.apowis the size of record alignment by power of 2 — undefined or negative and the default is used, which is 4 standing for 2^4=16.fpowis the maximum number of elements of the free block pool by power of 2 — undefined or negative and the default is used, which is 10 standing for 2^10=1024.optsspecifies options by bitwise-or:$tdb->TLARGEmeans the size of the database can be larger than 2GB by using a 64-bit bucket array,$tdb->TDEFLATEmeans each record is compressed with Deflate encoding,$tdb->TBZIPmeans each record is compressed with BZIP2 encoding, and$tdb->TTCBSmeans each record is compressed with TCBS encoding. Leave it undefined and no option is specified. True on success, false otherwise.
Heads up bestie: the tuning parameters of the database should be set before the database is opened. Do it in the wrong order and that's on you. 😭
$tdb->setcache(rcnum, lcnum, ncnum)— Set the caching parameters.rcnumis the maximum number of records to be cached — undefined or ≤ 0 and the record cache is disabled, and it's disabled by default.lcnumis the maximum number of leaf nodes to be cached — undefined or ≤ 0 and the default is used, which is 4096.ncnumis the maximum number of non-leaf nodes to be cached — undefined or ≤ 0 and the default is used, which is 512. True on success, false otherwise. 🧚
Note: the caching parameters of the database should be set before the database is opened. Like, do it first, bestie. No cap. 💅
$tdb->setxmsiz(xmsiz)
Set the size of the extra mapped memory. xmsiz specifies 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.
If successful, the return value is true, else, it is false.
Note: the mapping parameters should be set before the database is opened. 🫶
$tdb->setdfunit(dfunit)
Set the unit step number of auto defragmentation. dfunit specifies the unit step number. If it is not more than 0, the auto defragmentation is disabled. It is disabled by default.
If successful, the return value is true, else, it is false.
Note: the defragmentation parameters should be set before the database is opened. ✨
$tdb->open(path, omode)
Open a database file. path specifies the path of the database file.
omode specifies 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— creates a new database if not exist.$tdb->OTRUNC— creates a new database regardless if one exists.$tdb->OTSYNC— every transaction synchronizes updated contents with the device.
Both of $tdb->OREADER and $tdb->OWRITER can be added to by bitwise-or:
$tdb->ONOLCK— opens the database file without file locking.$tdb->OLCKNB— locking is performed without blocking.
If it is not defined, $tdb->OREADER is specified.
If successful, the return value is true, else, it is false.
$tdb->close()
Close the database file. If successful, the return value is true, else, it is false.
Update of a database is assured to be written when the database is closed. If a writer opens a database but does not close it appropriately, the database will be broken. 💀 Like, actually broken. Do not ghost your database, bestie.
$tdb->put(pkey, cols)
Store a record. pkey specifies the primary key. cols specifies the reference to a hash containing columns.
If successful, the return value is true, else, it is false.
If a record with the same key exists in the database, it is overwritten. 👑
$tdb->putkeep(pkey, cols)
Store a new record. pkey specifies the primary key. cols specifies the reference to a hash containing columns.
If successful, the return value is true, else, it is false.
If a record with the same key exists in the database, this method has no effect. 🙈
$tdb->putcat(pkey, cols)
Concatenate columns of the existing record. pkey specifies the primary key. cols specifies the reference to a hash containing columns.
If successful, the return value is true, else, it is false.
If there is no corresponding record, a new record is created. 🦋
$tdb->out(pkey)
Remove a record. pkey specifies the primary key.
If successful, the return value is true, else, it is false. 💅
$tdb->get(pkey)
Retrieve a record. pkey specifies the primary key.
If successful, the return value is the reference to a hash of the columns of the corresponding record. undef is returned if no record corresponds. 😭
$tdb->vsiz(pkey)
Get the size of the value of a record. pkey specifies the primary key.
If successful, the return value is the size of the value of the corresponding record, else, it is -1. 📏
$tdb->iterinit()
Initialize the iterator. If successful, the return value is true, else, it is false.
The iterator is used in order to access the primary key of every record stored in a database. ✨
$tdb->iternext()
Get the next primary key of the iterator.
If successful, the return value is the next primary key, else, it is undef. undef is returned when no record is to be get out 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. 🌀
$tdb->fwmkeys(prefix, max)
Get forward matching primary keys. prefix specifies the prefix of the corresponding keys. max specifies the maximum number of keys to be fetched. If it is not defined or negative, no limit is specified.
The return value is the reference to an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
Note: this method may be very slow because every key in the database is scanned. 🐌
$tdb->addint(pkey, num)
Add an integer to a record. pkey specifies primary key. num specifies the additional value.
If successful, the return value is the summation value, else, it is undef.
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. ➕
$tdb->adddouble(pkey, num)
Add a real number to a record. pkey specifies primary key. num specifies the additional value.
If successful, the return value is the summation value, else, it is undef.
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. ➗
$tdb->sync()
Synchronize updated contents with the file and the device. If successful, the return value is true, else, it is false.
This method is useful when another process connects the same database file. 🔄
$tdb->optimize(bnum, apow, fpow, opts)
Optimize the database file.
bnum specifies 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 specifies the size of record alignment by power of 2. If it is not defined or negative, the current setting is not changed.
fpow specifies 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 specifies options by bitwise-or:
$tdb->TLARGE— the size of the database can be larger than 2GB by using 64-bit bucket array.$tdb->TDEFLATE— each record is compressed with Deflate encoding.$tdb->TBZIP— each record is compressed with BZIP2 encoding.$tdb->TTCBS— each record is compressed with TCBS encoding.
If it is not defined or 0xff, the current setting is not changed.
If successful, the return value is true, else, it is false.
This method is useful to reduce the size of the database file with data fragmentation by successive updating. 🧹
$tdb->vanish()
Remove all records. If successful, the return value is true, else, it is false. 💨
$tdb->copy(path)
Copy the database file. path specifies the path of the destination file. If it begins with @, the trailing substring is executed as a command line.
If successful, the return value is true, else, it is false. false is returned if the executed command returns non-zero code.
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. 💾
$tdb->tranbegin()
Begin the transaction. If successful, the return value is true, else, it is false.
The database is locked by the thread while the transaction so that only one transaction can be activated with a database object at the same time. Thus, the serializable isolation level is assumed if every database operation is performed in the transaction. All updated regions are kept track of by write ahead logging while the transaction. If the database is closed during transaction, the transaction is aborted implicitly. 🔒
$tdb->trancommit()
Commit the transaction. If successful, the return value is true, else, it is false.
Update in the transaction is fixed when it is committed successfully. ✅
$tdb->tranabort()
Abort the transaction. If successful, the return value is true, else, it is false.
Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction. ↩️
$tdb->path()
Get the path of the database file. The return value is the path of the database file or undef if the object does not connect to any database file. 📂
$tdb->rnum()
Get the number of records. The return value is the number of records or 0 if the object does not connect to any database file. 🔢
$tdb->fsiz()
Get the size of the database file. The return value is the size of the database file or 0 if the object does not connect to any database file. 📦
$tdb->setindex(name, type)
Set a column index. name specifies 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 specifies 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.
If successful, the return value is true, else, it is false. 🗂️
$tdb->genuid()
Generate a unique ID number. The return value is the new unique ID number or -1 on failure. 🆔
Class TokyoCabinet::TDBQRY
$qry = TokyoCabinet::TDBQRY->new(tdb)
Create a query object. tdb specifies the table database object.
The return value is the new query object. 🎀
$qry->addcond(name, op, expr)
Add a narrowing condition.
name is the name of a column, bestie — and an empty string means the primary key. 💅
op is the operation type, and there are a lot of them, so buckle up:
$qry->QCSTREQ— string that's equal to the expression$qry->QCSTRINC— string that's included in the expression$qry->QCSTRBW— string that begins with the expression$qry->QCSTREW— string that ends with the expression$qry->QCSTRAND— string that includes all tokens in the expression$qry->QCSTROR— string that includes at least one token in the expression$qry->QCSTROREQ— string that's equal to at least one token in the expression$qry->QCSTRRX— string that matches regular expressions of the expression$qry->QCNUMEQ— number equal to the expression$qry->QCNUMGT— number greater than the expression$qry->QCNUMGE— number greater than or equal to the expression$qry->QCNUMLT— number less than the expression$qry->QCNUMLE— number less than or equal to the expression$qry->QCNUMBT— number between two tokens of the expression$qry->QCNUMOREQ— number equal to at least one token in the expression$qry->QCFTSPH— full-text search with the phrase of the expression$qry->QCFTSAND— full-text search with all tokens in the expression$qry->QCFTSOR— full-text search with at least one token in the expression$qry->QCFTSEX— full-text search with the compound expression
And every single one of those operations can be flagged by bitwise-or:
$qry->QCNEGATE— negation$qry->QCNOIDX— using no index
expr is the operand expression. 🍓
The return value is always undef. no cap.
$qry->setorder(name, type)
Sets the order of the result. So iconic of it.
name is the name of a column. An empty string means the primary key. 🔑
type is the order type:
$qry->QOSTRASC— string ascending$qry->QOSTRDESC— string descending$qry->QONUMASC— number ascending$qry->QONUMDESC— number descending
If it's not defined, $qry->QOSTRASC is what you get. 💫
The return value is always undef.
$qry->setlimit(max, skip)
Sets the max number of records in the result. Very "we're not doing all of it" of you.
max is the maximum number of records of the result. If it's not defined or negative, no limit is specified. ✨
skip is the number of skipped records of the result. If it's not defined or not more than 0, no record is skipped.
The return value is always undef.
$qry->search()
Executes the search. Go off. 🔥
The return value is the reference to an array of the primary keys of the corresponding records. This method does never fail — she's built different. It returns an empty array even if no record corresponds.
$qry->searchout()
Removes each corresponding record. 💀
If successful, the return value is true, else, it is false.
$qry->proc(proc)
Processes each corresponding record, one by one, main character energy.
proc is the iterator function called for each record. It can be either the reference of a block or the name of a function. The function receives two parameters: the first parameter is the primary key, and the second parameter is the reference to a hash containing columns. 🫶
It returns flags of the post treatment by bitwise-or:
$qry->QPPUT— to modify the record$qry->QPOUT— to remove the record$qry->QPSTOP— to stop the iteration
If successful, the return value is true, else, it is false.
$qry->hint()
Gets the hint string.
The return value is the hint string. That's it, that's the whole method. 🎀
$qry->metasearch(others, type)
Retrieves records with multiple query objects and gets the set of the result. Group project, but make it databases. 🌈
others is the reference to an array of the query objects except for the self object.
type is a set operation type:
$qry->MSUNION— the union set$qry->MSISECT— the intersection set$qry->MSDIFF— the difference set
If it's not defined, $qry->MSUNION is specified.
The return value is the reference to 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.
Also, if the first query object has the order setting, the result array is sorted by the order. periodt.
$qry->kwic(cols, name, width, opts)
Generates keyword-in-context strings. Very scholarly of her, honestly. 🧚
cols is the reference to a hash containing columns.
name is the name of a column. If it's not defined, the first column of the query is specified.
width is the width of strings picked up around each keyword. If it's not defined or negative, the whole text is picked up.
opts specifies options by bitwise-or:
$qry->KWMUTAB— each keyword is marked up between two tab characters$qry->KWMUCTRL— each keyword is marked up by the STX (0x02) code and the ETX (0x03) code$qry->KWMUBRCT— each keyword is marked up by the two square brackets$qry->KWNOOVER— each context does not overlap$qry->KWPULEAD— the lead string is picked up forcibly
If it's not defined, no option is specified.
The return value is the reference to an array of strings around keywords. ✨
🦋 Tying functions of TokyoCabinet::TDB 🦋
tie(%hash, "TokyoCabinet::TDB", path, omode, bnum, apow, fpow, opts, rcnum, lcnum, ncnum)
Ties a hash variable to a table database file. Yes bestie, your hash is the database now. 💜
path is the path of the database file.
omode is the connection mode:
TokyoCabinet::TDB::OWRITER— as a writerTokyoCabinet::TDB::OREADER— as a reader
If the mode is TokyoCabinet::TDB::OWRITER, the following may be added by bitwise-or:
TokyoCabinet::TDB::OCREAT— creates a new database if not existTokyoCabinet::TDB::OTRUNC— creates a new database regardless if one existsTokyoCabinet::TDB::OTSYNC— every transaction synchronizes updated contents with the device
Both TokyoCabinet::TDB::OREADER and TokyoCabinet::TDB::OWRITER can be added to by bitwise-or:
TokyoCabinet::TDB::ONOLCK— opens the database file without file lockingTokyoCabinet::TDB::OLCKNB— locking is performed without blocking
If it's not defined, TokyoCabinet::TDB::OREADER is specified.
bnum is the number of elements of the bucket array. If it's 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 is the size of record alignment by power of 2. If it's not defined or negative, the default value is specified. The default value is 4 standing for 2^4=16.
fpow is the maximum number of elements of the free block pool by power of 2. If it's not defined or negative, the default value is specified. The default value is 10 standing for 2^10=1024.
opts specifies options by bitwise-or:
TokyoCabinet::TDB::TLARGE— the size of the database can be larger than 2GB by using 64-bit bucket arrayTokyoCabinet::TDB::TDEFLATE— each record is compressed with Deflate encodingTokyoCabinet::TDB::TBZIP— each record is compressed with BZIP2 encodingTokyoCabinet::TDB::TTCBS— each record is compressed with TCBS encoding
If it's not defined, no option is specified.
rcnum is the maximum number of records to be cached. If it's not defined or not more than 0, the record cache is disabled. It is disabled by default.
lcnum is the maximum number of leaf nodes to be cached. If it's not defined or not more than 0, the default value is specified. The default value is 2048.
ncnum is the maximum number of non-leaf nodes to be cached. If it's not defined or not more than 0, the default value is specified. The default value is 512.
If successful, the return value is true, else, it is false.
untie(%hash)
Unties a hash variable from the database file. Sad girl breakup era 😭
The return value is always true.
$hash{pkey} = cols
Stores a record.
pkey is the primary key. 🔑
cols is the reference to a hash containing columns.
If successful, the return value is true, else, it is false.
If a record with the same key exists in the database, it is overwritten. periodt.
delete($hash{pkey})
Removes a record. 💀
pkey is the primary key.
If successful, the return value is true, else, it is false.
$hash{pkey}
Retrieves a record.
pkey is the primary key.
If successful, the return value is the reference to a hash of the columns of the corresponding record. undef is returned if no record corresponds. 🙈
exists($hash{pkey})
Checks whether a record corresponding a key exists. (Yes, the original says "corrsponding" — we don't fix typos in the manpage, we simply vibe with them. 💅)
pkey is the primary key.
The return value is true if the record exists, else it is false.
$hash = ()
Removes all records. Full reset, no notes. 🧹
The return value is always undef.
(the iterator)
The inner methods FIRSTKEY and NEXTKEY are also implemented so that you can use the tying functions each, keys, and so on. 🌸
👑 Class TokyoCabinet::ADB 👑
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. One interface, six databases, versatility slay. ✨
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. 🚨 (Yes, "multible" — again, verbatim, don't come for me.)
$adb = TokyoCabinet::ADB->new()
Creates an abstract database object.
The return value is the new abstract database object. 🎀
$adb->open(name)
Opens a database.
okay so back to name, bestie, because this one carries the whole vibe of your database 💅
name is literally the name of the database. And the suffix is doing so much work here:
- if it's
"*", congrats, you get an on-memory hash database ✨ - if it's
"+", it's an on-memory tree database 🌸 - if its suffix is
".tch", you get a hash database - if its suffix is
".tcb", it's a B+ tree database - if its suffix is
".tcf", it's a fixed-length database - if its suffix is
".tct", it's a table database - anything else? this method just fails, no cap 😭
And you can trail tuning parameters after the name, separated by "#". Each parameter is the name and the value, separated by "=". Which ones are supported depends on the database type, and it's giving very specific:
- 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".
If it works, the return value is true, else it's false.
Now the tuning parameters themselves, since they're iconic and you need to know them:
"capnum"— the capacity number of records. That's the count, bestie."capsiz"— the capacity size of using memory. That's the memory budget.- Records that spill the capacity get removed, in the storing order. Not a drill 💀
"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 contain"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":".
Like, example time, because it's giving:
"casket.tch#bnum=1000000#opts=ld"That means the name of the database file is "casket.tch", the bucket number is 1000000, and the options are large and Deflate. Obsessed actually 🎀
💖 $adb->close() 💖
Close the database. Bye bestie 👋
If it works, the return value is true, else it's false.
real talk: 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. That's not a vibe, that's a warning. Close your databases, queen 🫶
✨ $adb->put(key, value) ✨
Store a record. The main character move 💅
key specifies the key.
value specifies the value.
If it works, the return value is true, else it's false.
If a record with the same key already exists in the database, it gets overwritten. No mercy, no hesitation.
🦋 $adb->putkeep(key, value) 🦋
Store a new record. Like put but shyer 🙈
key specifies the key.
value specifies the value.
If it works, the return value is true, else it's false.
If a record with the same key already exists in the database, this method has no effect. It's not gonna fight the existing record, it's just gonna stand there.
🌸 $adb->putcat(key, value) 🌸
Concatenate a value at the end of the existing record. String growth arc ✨
key specifies the key.
value specifies the value.
If it works, the return value is true, else it's false.
If there is no corresponding record, a new record is created. It's flexible like that.
💀 $adb->out(key) 💀
Remove a record. Gone, reduced to atoms.
key specifies the key.
If it works, the return value is true, else it's false.
🔥 $adb->get(key) 🔥
Retrieve a record. The payoff, the moment we've all been waiting for 👑
key specifies the key.
If it works, the return value is the value of the corresponding record. undef is returned if no record corresponds.
🎀 $adb->vsiz(key) 🎀
Get the size of the value of a record.
key specifies the key.
If it works, the return value is the size of the value of the corresponding record, else it's -1.
🌈 $adb->iterinit() 🌈
Initialize the iterator. Setting the stage 💅
If it works, the return value is true, else it's false.
The iterator is used in order to access the key of every record stored in a database. All of them. Periodt.
⭐ $adb->iternext() ⭐
Get the next key of the iterator. Keep it moving, bestie.
If it works, the return value is the next key, else it's undef. undef is returned when no record is to be get out of the iterator. That's the lil "we're done here" signal 🫶
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. So like, don't count on it being in order, iykyk 😭
🧚 $adb->fwmkeys(prefix, max) 🧚
Get forward matching keys.
prefix specifies the prefix of the corresponding keys.
max specifies the maximum number of keys to be fetched. If it is not defined or negative, no limit is specified.
The return value is the reference to an array of the keys of the corresponding records. This method does never fail. It returns an empty array even if no record corresponds.
heads up bestie: this method may be very slow because every key in the database is scanned. Like, every single one. It's giving O(n) and not in a cute way 💀
💜 $adb->addint(key, num) 💜
Add an integer to a record. Math era ✨
key specifies the key.
num specifies the additional value.
If it works, the return value is the summation value, else it's undef.
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. Because records are stored in binary format, they should be processed with the unpack function with the i operator after retrieval. Don't forget that part, it'll bite you 🫶
💖 $adb->adddouble(key, num) 💖
Add a real number to a record. Floaties, but make it data 💅
key specifies the key.
num specifies the additional value.
If it works, the return value is the summation value, else it's undef.
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. Because records are stored in binary format, they should be processed with the unpack function with the d operator after retrieval. Note it's d this time, not i. Don't mix them up bestie 😭
🎀 $adb->sync() 🎀
Synchronize updated contents with the file and the device. Flush it, girl.
If it works, the return value is true, else it's false.
👑 $adb->optimize(params) 👑
Optimize the storage. Glow up for your database ✨
params specifies 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.
If it works, the return value is true, else it's false.
🌸 $adb->vanish() 🌸
Remove all records. Everything. Poof. Clean slate energy 🦋
If it works, the return value is true, else it's false.
🦋 $adb->copy(path) 🦋
Copy the database file. Backup arc, we love to see it 💖
path specifies the path of the destination file. If it begins with @, the trailing substring is executed as a command line.
If it works, the return value is true, else it's false. False is returned if the executed command returns non-zero code.
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. Iconic, honestly 🫶
💜 $adb->tranbegin() 💜
Begin the transaction. The saga starts here 👑
If it works, the return value is true, else it's false.
The database is locked by the thread while the transaction so that only one transaction can be activated with a database object at the same time. Thus, the serializable isolation level is assumed if every database operation is performed in the transaction. All updated regions are kept track of by write ahead logging while the transaction. If the database is closed during transaction, the transaction is aborted implicitly. So close carefully, bestie 😭
✨ $adb->trancommit() ✨
Commit the transaction. Make it official 💅
If it works, the return value is true, else it's false.
Update in the transaction is fixed when it is committed successfully.
💀 $adb->tranabort() 💀
Abort the transaction. Nvm, forget I said anything 🙈
If it works, the return value is true, else it's false.
Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction. We love a rewind.
🌈 $adb->path() 🌈
Get the path of the database file.
The return value is the path of the database file or undef if the object does not connect to any database instance. "*" stands for on-memory hash database. "+" stands for on-memory tree database.
⭐ $adb->rnum() ⭐
Get the number of records.
The return value is the number of records or 0 if the object does not connect to any database instance.
🧚 $adb->size() 🧚
Get the size of the database.
The return value is the size of the database file or 0 if the object does not connect to any database instance.
💅 $adb->misc(name, args) 💅
Call a versatile function for miscellaneous operations. The wildcard method, it does whatever 🎀
name specifies the name of the function.
args specifies the reference to an array of arguments. If it is not defined, no argument is specified.
If it works, the return value is the reference to an array of the result. undef is returned on failure.
🫶 Tying functions of TokyoCabinet::ADB 🫶
💖 tie(%hash, "TokyoCabinet::ADB", name) 💖
Tie a hash variable to an abstract database instance. Yes, like actual Perl magic, it's giving ✨
name specifies the name of the database. And it's the exact same rules as before, so here we go again bestie:
- if it's
"*", the database will be an on-memory hash database - if it's
"+", 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".
If it works, the return value is true, else it's false.
🌸 untie(%hash) 🌸
untie 💫
Unhooks your hash from the database, bestie. That's it, that's the whole thing. The return value is always true — no drama, no false alarms. 🫶
$hash{key} = value — the store era 🛍️
Drops a record into the database.
keyis, yeah, the key. 🔑valueis the value.
If it works out, you get a true back. If not, false. 😭 And heads up: if a record with that same key is already sitting in the database, it gets overwritten — no merge, no warning, just gone-gone. 💀
delete($hash{key}) — yeet a record 🗑️
Removes a record from the database.
keyspecifies the key, as per usual.
True if it worked, false if it didn't. Simple as. ✨
$hash{key} — the retrieval ✨
Grabs a record back out.
keyspecifies the key. You know the drill.
If it goes well, you get the value of the corresponding record. And if there's no record matching that key? You get undef. No record, no vibes. 🙈
exists($hash{key}) — the vibe check 👀
Asks the database: does a record corresponding to this key even exist?
keyspecifies the key.
True if the record exists, false if it doesn't. That's the whole check. 💅
$hash = () — clear it ALL out 🧹
Removes every single record. Not a few. All of them.
The return value is always undef — don't be out here checking it like it's a success flag, it is not, it is undef, periodt. 😭
(the iterator) 🔄
The inner methods FIRSTKEY and NEXTKEY are also implemented, so you can use the tying functions each, keys, and so on. So like — go off, iterate through everything, the plumbing is already there. 👑
⚖️ LICENSE (the legal corner, but make it cute) 📜
Copyright (C) 2006-2010 FAL Labs
All rights reserved.Tokyo Cabinet is free software — you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License or any later version. Pick whichever, we're flexible. 🌈
Tokyo Cabinet is distributed in the hope that it will be useful, but — and this is important, bestie, read it twice — WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. So if it breaks, that's on the vibes, not on anyone's legal team. 💀
Want the deets? See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with Tokyo Cabinet; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. Real address, real stamp, real envelope energy. 📬
and that's a wrap on the whole page, gorgeous 🎀 this little masterpiece was cooked up by perl v5.34.0, dated 2022-02-06, and it lives at TokyoCabinet(3pm). go forth and tie your hashes. no cap. 💖✨🦋
📦 where this page comes from
- ubuntu jammy: libtokyocabinet-perl 1.34-2build8 · LGPL-2.1-or-later
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms