TCTDB(3)

📦
version 1.4.48 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 TCTDB 🎀

okay bestie, welcome to tctdb — that's the table database API, and it lives in manual section 3 of Tokyo Cabinet. this is part 1 of 5, so buckle up, we're going on a journey 💖

✨ NAME ✨

tctdb — the table database API 🫶

💫 DESCRIPTION 💫

so. a table database is literally just a file, and that file contains records. each record is made of primary keys + arbitrary columns, and you talk to the whole thing through the table database API. that's it, that's the vibe ✨

to use the table database API, you gotta include tcutil.h, tctdb.h, and the related standard header files. usually you write this lil incantation near the front of your source file:

#include <tcutil.h>
#include <tctdb.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>

objects whose type is pointer to TCTDB are what you use to handle table databases. a table database object gets created with tctdbnew and deleted with tctdbdel. to avoid memory leak, it is important to delete every object when it is no longer in use. no cap, every single one 🧚

before you can store or retrieve records, you have to open a database file and connect the table database object to it. tctdbopen opens a database file, tctdbclose closes it. to avoid data missing or corruption, it is important to close every database file when it is no longer in use. and heads up — it is forbidden for multiple database objects in a process to open the same database at the same time. not even a little. don't do it 💀

🌈 API 🌈

tctdberrmsg

the function tctdberrmsg is how you get the message string corresponding to an error code.

const char *tctdberrmsg(int ecode);
  • ecode specifies the error code.
  • the return value is the message string of the error code.

tctdbnew

the function tctdbnew creates a table database object. iconic behavior.

TCTDB *tctdbnew(void);
  • the return value is the new table database object.

tctdbdel

the function tctdbdel deletes a table database object.

void tctdbdel(TCTDB *tdb);
  • tdb specifies the table database object.
  • if the database is not closed, it is closed implicitly.
  • note that the deleted object and its derivatives can not be used anymore. like, gone gone. do not touch 🫠

tctdbecode

the function tctdbecode gets the last happened error code of a table database object.

int tctdbecode(TCTDB *tdb);
  • tdb specifies the table database object.
  • the return value is the last happened error code.

the following error codes are defined:

  • TCESUCCESS for success ✨
  • TCETHREAD for threading error
  • TCEINVALID for invalid operation
  • TCENOFILE for file not found
  • TCENOPERM for no permission
  • TCEMETA for invalid meta data
  • TCERHEAD for invalid record header
  • TCEOPEN for open error
  • TCECLOSE for close error
  • TCETRUNC for trunc error
  • TCESYNC for sync error
  • TCESTAT for stat error
  • TCESEEK for seek error
  • TCEREAD for read error
  • TCEWRITE for write error
  • TCEMMAP for mmap error
  • TCELOCK for lock error
  • TCEUNLINK for unlink error
  • TCERENAME for rename error
  • TCEMKDIR for mkdir error
  • TCERMDIR for rmdir error
  • TCEKEEP for existing record
  • TCENOREC for no record found
  • TCEMISC for miscellaneous error

tctdbsetmutex

the function tctdbsetmutex sets mutual exclusion control of a table database object for threading.

bool tctdbsetmutex(TCTDB *tdb);
  • tdb specifies the table database object which is not opened.
  • if successful, the return value is true, else, it is false.
  • note that the mutual exclusion control is needed if the object is shared by plural threads, and this function should be called before the database is opened. order matters, bestie 🙏

tctdbtune

the function tctdbtune sets the tuning parameters of a table database object.

bool tctdbtune(TCTDB *tdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
  • tdb specifies the table database object which is not opened.
  • bnum specifies the number of elements of the bucket array. if it is 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 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 negative, the default value is specified. the default value is 10, standing for 2^10=1024.
  • opts specifies options by bitwise-or:
    • TDBTLARGE specifies that the size of the database can be larger than 2GB by using 64-bit bucket array
    • TDBTDEFLATE specifies that each record is compressed with Deflate encoding
    • TDBTBZIP specifies that each record is compressed with BZIP2 encoding
    • TDBTTCBS specifies that each record is compressed with TCBS encoding
  • if successful, the return value is true, else, it is false.
  • note that the tuning parameters should be set before the database is opened.

tctdbsetcache

the function tctdbsetcache sets the caching parameters of a table database object.

bool tctdbsetcache(TCTDB *tdb, int32_t rcnum, int32_t lcnum, int32_t ncnum);
  • tdb specifies the table database object which is not opened.
  • rcnum specifies the maximum number of records to be cached. if it is not more than 0, the record cache is disabled. it is disabled by default.
  • lcnum specifies the maximum number of leaf nodes to be cached. if it is not more than 0, the default value is specified. the default value is 4096.
  • ncnum specifies the maximum number of non-leaf nodes to be cached. if it is 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 should be set before the database is opened. leaf nodes and non-leaf nodes are used in column indices, iykyk 🌸

tctdbsetxmsiz

the function tctdbsetxmsiz sets the size of the extra mapped memory of a table database object.

bool tctdbsetxmsiz(TCTDB *tdb, int64_t xmsiz);
  • tdb specifies the table database object which is not opened.
  • xmsiz specifies the size of the extra mapped memory. if it is 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.

tctdbsetdfunit

the function tctdbsetdfunit sets the unit step number of auto defragmentation of a table database object.

bool tctdbsetdfunit(TCTDB *tdb, int32_t dfunit);
  • tdb specifies the table database object which is not opened.
  • 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.

tctdbopen

the function tctdbopen opens a database file and connects a table database object.

bool tctdbopen(TCTDB *tdb, const char *path, int omode);
  • tdb specifies the table database object which is not opened.
  • path specifies the path of the database file.
  • omode specifies the connection mode: TDBOWRITER as a writer, TDBOREADER as a reader. if the mode is TDBOWRITER, the following may be added by bitwise-or:
    • TDBOCREAT, which means it creates a new database if not exist
    • TDBOTRUNC, which means it creates a new database regardless if one exists
    • TDBOTSYNC, which means every transaction synchronizes updated contents with the device
  • both of TDBOREADER and TDBOWRITER can be added to by bitwise-or:
    • TDBONOLCK, which means it opens the database file without file locking
    • TDBOLCKNB, which means locking is performed without blocking
  • if successful, the return value is true, else, it is false.

tctdbclose

the function tctdbclose closes a table database object.

bool tctdbclose(TCTDB *tdb);
  • tdb specifies the table database object.
  • if successful, the return value is true, else, it is false.
  • update of a database is assured to be written when the database is closed.
⚠️ if a writer opens a database but does not close it appropriately, the database will be broken. like, broken broken. please close your databases, bestie, this is the whole plot 😭

tctdbput

the function tctdbput stores a record into a table database object.

bool tctdbput(TCTDB *tdb, const void *pkbuf, int pksiz, TCMAP *cols);
  • tdb specifies the table database object connected as a writer.
  • pkbuf specifies the pointer to the region of the primary key.
  • pksiz specifies the size of the region of the primary key.
  • cols specifies a map object 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. (so lowkey mind your keys 💅)

tctdbput2

the function tctdbput2 is used in order to store a string record into a table database object with a zero separated column string.

…and that's where part 1 ends, bestie — more parts are coming, so stay tuned 🦋

tctdbput2 — zero-separated string, overwrite energy 💅

bool tctdbput2(TCTDB *tdb, const void *pkbuf, int pksiz, const void *cbuf, int csiz);
  • tdb — the table database object, and bestie she has to be connected as a writer. No reader vibes allowed here.
  • pkbuf — pointer to the region of the primary key.
  • pksiz — the size of the region of the primary key.
  • cbuf — pointer to the region of the zero separated column string, where the name and the value of each column are situated one after the other.
  • csiz — the size of the region of the column string.

If it works out, the return value is true; if not, it's false. 😭

And if a record with the same key already exists in the database? It gets overwritten. Like, gone. Replaced. Main character took the throne. 👑

tctdbput3 — tab-separated string, also overwrites 🎀

The function tctdbput3 is the one you call to store a string record into a table database object using a tab separated column string.

bool tctdbput3(TCTDB *tdb, const char *pkstr, const char *cstr);
  • tdb — the table database object connected as a writer.
  • pkstr — the string of the primary key.
  • cstr — the string of the tab separated column string, where the name and the value of each column are situated one after the other.

Success → true. Not success → false.

Same deal as before, no cap: if a record with the same key exists in the database, it is overwritten. ✨

tctdbputkeep — new record only, don't touch what's already there 🙈

The function tctdbputkeep stores a new record into a table database object. It's giving "respectful, doesn't overwrite."

bool tctdbputkeep(TCTDB *tdb, const void *pkbuf, int pksiz, TCMAP *cols);
  • tdb — the table database object connected as a writer.
  • pkbuf — pointer to the region of the primary key.
  • pksiz — the size of the region of the primary key.
  • cols — a map object containing columns.

true on success, false otherwise. 🫶

If a record with the same key exists in the database, this function has no effect. It just… doesn't. She said nope. 💀

tctdbputkeep2 — new string record, zero separated 🦋

The function tctdbputkeep2 stores a new string record into a table database object using a zero separated column string.

bool tctdbputkeep2(TCTDB *tdb, const void *pkbuf, int pksiz, const void *cbuf, int csiz);
  • tdb — the table database object connected as a writer.
  • pkbuf — pointer to the region of the primary key.
  • pksiz — the size of the region of the primary key.
  • cbuf — pointer to the region of the zero separated column string, where the name and the value of each column are situated one after the other.
  • csiz — the size of the region of the column string.

true if it ate, false if it didn't. 😌

Existing record with the same key? This function has no effect at all. Zero. Nada. 🔥

tctdbputkeep3 — new string record, tab separated 🌸

The function tctdbputkeep3 stores a new string record into a table database object using a tab separated column string.

bool tctdbputkeep3(TCTDB *tdb, const char *pkstr, const char *cstr);
  • tdb — the table database object connected as a writer.
  • pkstr — the string of the primary key.
  • cstr — the string of the tab separated column string, where the name and the value of each column are situated one after the other.

true = slay. false = not slay. 💅

And again, if a record with the same key exists in the database, this function has no effect. She's polite like that. 🎀

tctdbputcat — concatenate onto an existing record 🧚

The function tctdbputcat concatenates columns of the existing record in a table database object. It's the "add to the vibe that's already there" one.

bool tctdbputcat(TCTDB *tdb, const void *pkbuf, int pksiz, TCMAP *cols);
  • tdb — the table database object connected as a writer.
  • pkbuf — pointer to the region of the primary key.
  • pksiz — the size of the region of the primary key.
  • cols — a map object containing columns.

true on success, false on sadness. 😭

And if there's no corresponding record? No problem bestie, a new record is created. She's generous. ✨

tctdbputcat2 — concatenate with a zero separated column string 💜

The function tctdbputcat2 concatenates columns in a table database object using a zero separated column string.

bool tctdbputcat2(TCTDB *tdb, const void *pkbuf, int pksiz, const void *cbuf, int csiz);
  • tdb — the table database object connected as a writer.
  • pkbuf — pointer to the region of the primary key.
  • pksiz — the size of the region of the primary key.
  • cbuf — pointer to the region of the zero separated column string, where the name and the value of each column are situated one after the other.
  • csiz — the size of the region of the column string.

true if it worked, false if it didn't. 🫶

No corresponding record? A new record is created. Same energy as above, periodt. 👑

tctdbputcat3 — concatenate with a tab separated column string 🌈

The function tctdbputcat3 concatenates columns in a table database object using a tab separated column string.

bool tctdbputcat3(TCTDB *tdb, const char *pkstr, const char *cstr);
  • tdb — the table database object connected as a writer.
  • pkstr — the string of the primary key.
  • cstr — the string of the tab separated column string, where the name and the value of each column are situated one after the other.

true / false, you know the drill by now. 💅

If there is no corresponding record, a new record is created. Iconic behaviour, honestly. ⭐

tctdbout — bye bye record 🦋

The function tctdbout removes a record from a table database object.

bool tctdbout(TCTDB *tdb, const void *pkbuf, int pksiz);
  • tdb — the table database object connected as a writer.
  • pkbuf — pointer to the region of the primary key.
  • pksiz — the size of the region of the primary key.

If successful, the return value is true; otherwise it's false. 🫶

tctdbout2 — bye bye string record 🎀

The function tctdbout2 removes a string record from a table database object.

bool tctdbout2(TCTDB *tdb, const char *pkstr);
  • tdb — the table database object connected as a writer.
  • pkstr — the string of the primary key.

true if it went through, false if it didn't. 💜

tctdbget — retrieving a whole record as a map 🍓

The function tctdbget retrieves a record from a table database object.

TCMAP *tctdbget(TCTDB *tdb, const void *pkbuf, int pksiz);
  • tdb — the table database object.
  • pkbuf — pointer to the region of the primary key.
  • pksiz — the size of the region of the primary key.

If successful, the return value is a map object of the columns of the corresponding record. If no record corresponds, NULL is returned. 😭

Heads up bestie, this one matters: because the object of the return value is created with the function tcmapnew, it should be deleted with the function tcmapdel when it is no longer in use. Don't just leave it lying around, that's not the vibe. 🙈

tctdbget2 — retrieving a record as a zero separated column string 🌸

The function tctdbget2 retrieves a record from a table database object as a zero separated column string.

char *tctdbget2(TCTDB *tdb, const void *pkbuf, int pksiz, int *sp);
  • tdb — the table database object.
  • pkbuf — pointer to the region of the primary key.
  • pksiz — the size of the region of the primary key.
  • sp — pointer to the variable into which the size of the region of the return value is assigned.

If successful, the return value is the pointer to the region of the column string of the corresponding record. NULL is returned if no record corresponds. 💀

Cute detail: because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. ✨
And because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use. Please actually free it. Memory leaks are not the moment. 😭

tctdbget3 — retrieving a string record as a tab separated column string 💖

The function tctdbget3 retrieves a string record from a table database object as a tab separated column string.

char *tctdbget3(TCTDB *tdb, const char *pkstr);
  • tdb — the table database object.
  • pkstr — the string of the primary key.

If successful, the return value is the tab separated column string of the corresponding record. NULL is returned if no record corresponds. 😭

Same rules as tctdbget2, no exceptions: because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use. 🫶

tctdbvsiz — size check incoming 👑

The function tctdbvsiz is used in order to get the size of the value of a record in a table database object.

tctdbvsiz is the little size-checker for a value when you already have the raw primary key bytes. 💅

int tctdbvsiz(TCTDB *tdb, const void *pkbuf, int pksiz);
  • tdb specifies the table database object.
  • kbuf specifies the pointer to the region of the primary key.
  • ksiz specifies the size of the region of the primary key.

If successful, the return value is the size of the value of the corresponding record, else, it is -1. No cap. ✨

The function tctdbvsiz2 is used in order to get the size of the value of a string record in a table database object. It’s giving string-key energy. 💖

int tctdbvsiz2(TCTDB *tdb, const char *pkstr);
  • tdb specifies the table database object.
  • kstr specifies the string of the primary key.

If successful, the return value is the size of the value of the corresponding record, else, it is -1. 🎀

The function tctdbiterinit is used in order to initialize the iterator of a table database object. Vibe check: iterator go brrr. 🦋

bool tctdbiterinit(TCTDB *tdb);
  • tdb specifies the table database object.

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. ✨

The function tctdbiternext is used in order to get the next primary key of the iterator of a table database object. The way that sp points to the size of the region… lowkey important. 😭

void *tctdbiternext(TCTDB *tdb, int *sp);
  • tdb specifies the table database object.
  • sp specifies the pointer to the variable into which the size of the region of the return value is assigned.

If successful, the return value is the pointer to the region of the next primary key, else, it is NULL. NULL is returned when no record is to be get out of the iterator. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use. It is possible to access every record by iteration of calling this function. It is allowed to update or remove records whose keys are fetched while the iteration. 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. 😭

The function tctdbiternext2 is used in order to get the next primary key string of the iterator of a table database object.

char *tctdbiternext2(TCTDB *tdb);
  • tdb specifies the table database object.

If successful, the return value is the string of the next primary key, else, it is NULL. NULL is returned when no record is to be get out of the iterator. Because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use. It is possible to access every record by iteration of calling this function. 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. ✨

The function tctdbiternext3 is used in order to get the columns of the next record of the iterator of a table database object. It’s giving map energy, fr fr. 👑

TCMAP *tctdbiternext3(TCTDB *tdb);
  • tdb specifies the table database object.

If successful, the return value is a map object of the columns of the next record, else, it is NULL. NULL is returned when no record is to be get out of the iterator. The primary key is added into the map as a column of an empty string key. Because the object of the return value is created with the function tcmapnew, it should be deleted with the function tcmapdel when it is no longer in use. It is possible to access every record by iteration of calling this function. 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. 👑

The function tctdbfwmkeys is used in order to get forward matching primary keys in a table database object.

TCLIST *tctdbfwmkeys(TCTDB *tdb, const void *pbuf, int psiz, int max);
  • tdb specifies the table database object.
  • pbuf specifies the pointer to the region of the prefix.
  • psiz specifies the size of the region of the prefix.
  • max specifies the maximum number of keys to be fetched. If it is negative, no limit is specified.

The return value is a list object of the corresponding keys. This function does never fail. It returns an empty list even if no key corresponds. Because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use. Ngl, this function may be very slow because every key in the database is scanned. 🐌

The function tctdbfwmkeys2 is used in order to get forward matching string primary keys in a table database object.

TCLIST *tctdbfwmkeys2(TCTDB *tdb, const char *pstr, int max);
  • tdb specifies the table database object.
  • pstr specifies the string of the prefix.
  • max specifies the maximum number of keys to be fetched. If it is negative, no limit is specified.

The return value is a list object of the corresponding keys. This function does never fail. It returns an empty list even if no key corresponds. Because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use. Note that this function may be very slow because every key in the database is scanned. 💀

The function tctdbaddint is used in order to add an integer to a column of a record in a table database object.

int tctdbaddint(TCTDB *tdb, const void *pkbuf, int pksiz, int num);
  • tdb specifies the table database object connected as a writer.
  • kbuf specifies the pointer to the region of the primary key.
  • ksiz specifies the size of the region of the primary key.
  • num specifies the additional value.

If successful, the return value is the summation value, else, it is INT_MIN. 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. 🔥

The function tctdbadddouble is used in order to add a real number to a column of a record in a table database object.

double tctdbadddouble(TCTDB *tdb, const void *pkbuf, int pksiz, double num);
  • tdb specifies the table database object connected as a writer.
  • kbuf specifies the pointer to the region of the primary key.
  • ksiz specifies the size of the region of the primary key.
  • num specifies the additional value.

If successful, the return value is the summation value, else, it is Not-a-Number. 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. 🌸

The function tctdbsync is used in order to synchronize updated contents of a table database object with the file and the device.

bool tctdbsync(TCTDB *tdb);
  • tdb specifies the table database object connected as a writer.

If successful, the return value is true, else, it is false. This function is useful when another process connects to the same database file. 💖

The function tctdboptimize is used in order to optimize the file of a table database object. It’s giving glow-up for your database. 🧚

bool tctdboptimize(TCTDB *tdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
  • tdb specifies the table database object connected as a writer.
  • bnum specifies the number of elements of the bucket array. If it is 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 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 negative, the current setting is not changed.
  • opts specifies options by bitwise-or: TDBTLARGE specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, TDBTDEFLATE specifies that each record is compressed with Deflate encoding, TDBTBZIP specifies that each record is compressed with BZIP2 encoding, TDBTTCBS specifies that each record is compressed with TCBS encoding. If it is UINT8_MAX, the current setting is not changed.

If successful, the return value is true, else, it is false. This function is useful to reduce the size of the database file with data fragmentation by successive updating. Periodt. 🧚

Okay so tctdbvanish</p> is the "delete everything, no thoughts, head empty" button 💀 — it removes all records of a table database object. All of them. Every single one. Gone.

bool tctdbvanish(TCTDB *tdb);
  • tdb — the table database object, and it has to be connected as a writer.
  • Returns true if it slayed, false if it didn't.

Next up, tctdbcopy</p> — it copies the database file of a table database object. It's giving backup bestie energy 🫶

bool tctdbcopy(TCTDB *tdb, const char *path);
  • tdb — the table database object.
  • path — where the destination file goes. And here's the fun part: if it begins with @, the trailing substring gets executed as a command line ✨
  • Returns true on success, false otherwise. And yes, false also comes back 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 fr fr, this function is genuinely useful for making a backup file of the database file. 💖

tctdbtranbegin</p> — starting a transaction, the moment before everything gets real.

bool tctdbtranbegin(TCTDB *tdb);
  • tdb — the table database object, connected as a writer.
  • Returns true if it worked, false if not.
  • The database gets locked by the thread for the duration, so only one transaction can be active on a database object at a time. Which means: the serializable isolation level is what you get, as long as every database operation happens inside the transaction.
  • Heads up though 👀 because all pages are cached in memory while the transaction runs, the amount of referred records is limited by the memory capacity.
  • And if the database is closed during a transaction? The transaction is aborted implicitly. Not a drill.

tctdbtrancommit</p> — committing the transaction, aka making it official 👑

bool tctdbtrancommit(TCTDB *tdb);
  • tdb — the table database object, connected as a writer.
  • Returns true if it worked, false if not.
  • The update in the transaction is fixed when it's committed successfully. Periodt.

tctdbtranabort</p> — the undo button, the "jk lol" of transactions 🙈

bool tctdbtranabort(TCTDB *tdb);
  • tdb — the table database object, connected as a writer.
  • Returns true if it worked, false if not.
  • The update in the transaction is discarded when it's aborted, and the state of the database gets rollbacked to before the transaction. Iconic behaviour honestly.

tctdbpath</p> — asks the database "where do you live" 🏠

const char *tctdbpath(TCTDB *tdb);
  • tdb — the table database object.
  • Returns the path of the database file, or NULL if the object isn't connected to any database file at all.

tctdbrnum</p> — how many records are we working with, bestie? 🔢

uint64_t tctdbrnum(TCTDB *tdb);
  • tdb — the table database object.
  • Returns the number of records, or 0 if the object isn't connected to any database file.

tctdbfsiz</p> — the size of the database file, in case you were wondering 📏

uint64_t tctdbfsiz(TCTDB *tdb);
  • tdb — the table database object.
  • Returns the size of the database file, or 0 if the object isn't connected to any database file.

tctdbsetindex</p> — setting a column index. This one has a LOT going on so let's get into it 💅

bool tctdbsetindex(TCTDB *tdb, const char *name, int type);
  • tdb — the table database object, connected as a writer.
  • name — the name of a column. If you name an index that already exists, that index gets rebuilt. And an empty string means the primary key.
  • type — the index type:
    • TDBITLEXICAL — for lexical string
    • TDBITDECIMAL — for decimal string
    • TDBITTOKEN — for token inverted index
    • TDBITQGRAM — for q-gram inverted index
    • TDBITOPT — the index gets optimized
    • TDBITVOID — the index gets removed
    • If TDBITKEEP is added by bitwise-or and the index exists, this function merely returns failure. No rebuild, no nothing.
  • Returns true on success, false otherwise.
Note that the setting indices should be set after the database is opened. Just trust the process on that one.

tctdbgenuid</p> — generating a fresh unique ID number 🎀

int64_t tctdbgenuid(TCTDB *tdb);
  • tdb — the table database object, connected as a writer.
  • Returns the new unique ID number, or -1 on failure.

tctdbqrynew</p> — creating a query object. Baby's first query ✨

TDBQRY *tctdbqrynew(TCTDB *tdb);
  • tdb — the table database object.
  • Returns the new query object.

tctdbqrydel</p> — deleting a query object. Clean up after yourself bestie 🧹

void tctdbqrydel(TDBQRY *qry);
  • qry — the query object.

tctdbqryaddcond</p> — adding a narrowing condition to a query object. This is where it gets ✨spicy✨ because there are SO many operation types.

void tctdbqryaddcond(TDBQRY *qry, const char *name, int op, const char *expr);
  • qry — the query object.
  • name — the name of a column. An empty string means the primary key.
  • op — the operation type, and there are a whole bunch:
    • TDBQCSTREQ — string which is equal to the expression
    • TDBQCSTRINC — string which is included in the expression
    • TDBQCSTRBW — string which begins with the expression
    • TDBQCSTREW — string which ends with the expression
    • TDBQCSTRAND — string which includes all tokens in the expression
    • TDBQCSTROR — string which includes at least one token in the expression
    • TDBQCSTROREQ — string which is equal to at least one token in the expression
    • TDBQCSTRRX — string which matches regular expressions of the expression
    • TDBQCNUMEQ — number which is equal to the expression
    • TDBQCNUMGT — number which is greater than the expression
    • TDBQCNUMGE — number which is greater than or equal to the expression
    • TDBQCNUMLT — number which is less than the expression
    • TDBQCNUMLE — number which is less than or equal to the expression
    • TDBQCNUMBT — number which is between two tokens of the expression
    • TDBQCNUMOREQ — number which is equal to at least one token in the expression
    • TDBQCFTSPH — full-text search with the phrase of the expression
    • TDBQCFTSAND — full-text search with all tokens in the expression
    • TDBQCFTSOR — full-text search with at least one token in the expression
    • TDBQCFTSEX — full-text search with the compound expression
  • And all of those operations can be flagged by bitwise-or:
    • TDBQCNEGATE — for negation
    • TDBQCNOIDX — for using no index
  • expr — the operand expression.

tctdbqrysetorder</p> — setting the order of a query object. Sorting is a personality trait 🌈

void tctdbqrysetorder(TDBQRY *qry, const char *name, int type);
  • qry — the query object.
  • name — the name of a column. An empty string means the primary key.
  • type — the order type:
    • TDBQOSTRASC — for string ascending
    • TDBQOSTRDESC — for string descending
    • TDBQONUMASC — for number ascending
    • TDBQONUMDESC — for number descending

tctdbqrysetlimit</p> — capping how many records come back, and how many you skip 🎯

void tctdbqrysetlimit(TDBQRY *qry, int max, int skip);
  • qry — the query object.
  • max — the maximum number of records of the result. If it's negative, no limit is specified.
  • skip — the number of skipped records of the result. If it's not more than 0, no record is skipped.

tctdbqrysearch</p> — executing the search. The moment of truth 🔥

TCLIST *tctdbqrysearch(TDBQRY *qry);
  • qry — the query object.
  • Returns a list object of the primary keys of the corresponding records. And get this — this function never fails. It returns an empty list even if no record corresponds. No drama, no errors, just vibes.
  • Because the returned object was created with tclistnew, you gotta delete it with tclistdel when you're done with it. Don't leave it hanging 🙈

tctdbqrysearchout</p> — removing each record corresponding to a query object. Search AND destroy 💀

bool tctdbqrysearchout(TDBQRY *qry);
  • qry — the query object of the database, connected as a writer.
  • Returns true on success, false otherwise.

tctdbqryproc</p> — processing each record corresponding to a query object.

  • bool tctdbqryproc(TDBQRY *qry, TDBQRYPROC proc, void *op); — okay bestie, this one iterates over your query results and lets you touch every single record as it goes by 👑
    • qry = the query object of the database connected as a writer. (writer mode only, no cap, don't come at me with a reader 🔥)
    • proc = the pointer to the iterator function that gets called for each record. It receives four parameters, in this exact order:
      1. the pointer to the region of the primary key
      2. the size of the region of the primary key
      3. a map object containing columns
      4. the pointer to the optional opaque object

And it returns flags of the post treatment, bitwise-or'd together:

  • TDBQPPUT — modify the record ✨
  • TDBQPOUT — remove the record 💀
  • TDBQPSTOP — stop the iteration 🛑
  • op = an arbitrary pointer handed to the iterator function as a parameter. Don't need it? Just pass NULL, she's chill 💅

If it works, the return value is true. If not, it's false. That's the whole vibe check.

The function tctdbqryhint is used in order to get the hint string of a query object 🔍

const char *tctdbqryhint(TDBQRY *qry);
  • qry = the query object, obviously.
  • The return value is the hint string. That's it. That's the tea ☕

The function tctdbmetasearch is used in order to retrieve records with multiple query objects and get the set of the result 🌈 this is the group-project of query functions, fr fr

TCLIST *tctdbmetasearch(TDBQRY **qrys, int num, int type);
  • qrys = an array of the query objects.
  • num = the number of elements of the array.
  • type = a set operation type, and you've got three flavours:
    • TDBMSUNION — the union set 🫶
    • TDBMSISECT — the intersection set 🎀
    • TDBMSDIFF — the difference set 🦋

The return value is a list object of the primary keys of the corresponding records. And here's the iconic part: this function does never fail. Not once. She simply does not miss 👑

  • It returns an empty list even if no record corresponds — no error, no drama, just vibes.
  • If the first query object has the order setting, the result array is sorted by the order ✨
  • Because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use. Clean up after yourself bestie, the memory doesn't free itself 😭

🌸 SEE ALSO 🌸

and that's the whole page, you made it to the end 🎉 This one's from the Tokyo Cabinet crew, shipped as Man Page, version date 2012-08-18, filed under TCTDB(3) — go forth and query, bestie, you absolutely ate 💖✨👑

📦 where this page comes from