TCBDB(3)

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

🌸 NAME 🌸

tcbdb — the B+ tree database API 💅

okay so real talk, this is the TCBDB(3) page from Tokyo Cabinet, and it's literally the whole entire manual for the B+ tree database API. bestie, we're going in, no cap. 🦋

✨ DESCRIPTION ✨

A B+ tree database is a file containing a B+ tree, and you handle it with the B+ tree database API. that's the whole vibe. 🌳

To use the B+ tree database API, include tcutil.h, tcbdb.h, and related standard header files. Usually, write the following description near the front of a source file:

#include <tcutil.h>
#include <tcbdb.h>
#include <stdlib.h>
#include <time.h>
#include <stdbool.h>
#include <stdint.h>

Objects whose type is pointer to TCBDB are used to handle B+ tree databases. A B+ tree database object is created with the function tcbdbnew and is deleted with the function tcbdbdel. To avoid memory leak, it is important to delete every object when it is no longer in use. like, every single one. don't leave them hanging, that's so not slay. 😭

Before operations to store or retrieve records, it is necessary to open a database file and connect the B+ tree database object to it. The function tcbdbopen is used to open a database file and the function tcbdbclose is used to close the database file. To avoid data missing or corruption, it is important to close every database file when it is no longer in use. 🫶

It is forbidden for multiple database objects in a process to open the same database at the same time. like, forbidden forbidden. 🚫

👑 API 👑

🎀 tcbdberrmsg — the error-code-to-message translator 🎀

The function tcbdberrmsg is used in order to get the message string corresponding to an error code.

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

🎀 tcbdbnew — birth of a database object 🎀

The function tcbdbnew is used in order to create a B+ tree database object.

TCBDB *tcbdbnew(void);
  • The return value is the new B+ tree database object.

🎀 tcbdbdel — delete the whole thing 🎀

The function tcbdbdel is used in order to delete a B+ tree database object.

void tcbdbdel(TCBDB *bdb);
  • bdb specifies the B+ tree 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. 💀 it's gone gone.

🎀 tcbdbecode — what went wrong, bestie? 🎀

The function tcbdbecode is used in order to get the last happened error code of a B+ tree database object.

int tcbdbecode(TCBDB *bdb);
  • bdb specifies the B+ tree 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

🎀 tcbdbsetmutex — threading protection, iconic 🎀

The function tcbdbsetmutex is used in order to set mutual exclusion control of a B+ tree database object for threading.

bool tcbdbsetmutex(TCBDB *bdb);
  • bdb specifies the B+ tree database object which is not opened.
  • If successful, the return value is true, else, it is false.
  • Note that the mutual exclusion control of the database should be set before the database is opened. 🔥

🎀 tcbdbsetcmpfunc — pick your own comparison energy 🎀

The function tcbdbsetcmpfunc is used in order to set the custom comparison function of a B+ tree database object.

bool tcbdbsetcmpfunc(TCBDB *bdb, TCCMP cmp, void *cmpop);
  • bdb specifies the B+ tree database object which is not opened.
  • cmp specifies the pointer to the custom comparison function. It receives five parameters. The first parameter is the pointer to the region of one key. The second parameter is the size of the region of one key. The third parameter is the pointer to the region of the other key. The fourth parameter is the size of the region of the other key. The fifth parameter is the pointer to the optional opaque object. It returns positive if the former is big, negative if the latter is big, 0 if both are equivalent.
  • cmpop specifies an arbitrary pointer to be given as a parameter of the comparison function. If it is not needed, NULL can be specified.
  • If successful, the return value is true, else, it is false.

The default comparison function compares keys of two records by lexical order. The functions tccmplexical (default), tccmpdecimal, tccmpint32, and tccmpint64 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. like, every single time, no shortcuts. 🙈

🎀 tcbdbtune — the tuning parameters, main character energy 🎀

The function tcbdbtune is used in order to set the tuning parameters of a B+ tree database object.

bool tcbdbtune(TCBDB *bdb, int32_t lmemb, int32_t nmemb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
  • bdb specifies the B+ tree database object which is not opened.
  • lmemb specifies the number of members in each leaf page. If it is 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 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 more than 0, the default value is specified. The default value is 16381. Suggested size of the bucket array is about from 1 to 4 times of the number of all pages 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 8 standing for 2^8=256.
  • 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: BDBTLARGE specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, BDBTDEFLATE specifies that each page is compressed with Deflate encoding, BDBTBZIP specifies that each page is compressed with BZIP2 encoding, BDBTTCBS specifies that each page 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. ⭐

🎀 tcbdbsetcache — cache it, queen 🎀

The function tcbdbsetcache is used in order to set the caching parameters of a B+ tree database object.

bool tcbdbsetcache(TCBDB *bdb, int32_t lcnum, int32_t ncnum);
  • bdb specifies the B+ tree database object which is not opened.
  • 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 1024.
  • 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. 💜

🎀 tcbdbsetxmsiz — extra mapped memory, the bonus level 🎀

The function tcbdbsetxmsiz is used in order to set the size of the extra mapped memory of a B+ tree database object.

bool tcbdbsetxmsiz(TCBDB *bdb, int64_t xmsiz);
  • bdb specifies the B+ tree 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. 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. ✨

🎀 tcbdbsetdfunit — auto defrag, glow-up mode 🎀

The function tcbdbsetdfunit is used in order to set the unit step number of auto defragmentation of a B+ tree database object.

bool tcbdbsetdfunit(TCBDB *bdb, int32_t dfunit);
  • bdb specifies the B+ tree database object which is not opened.
  • 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 that the defragmentation parameter should be set before the database is opened. 🧚

🎀 tcbdbopen — open the file, connect the object 🎀

The function tcbdbopen is used in order to open a database file and connect a B+ tree database object.

bool tcbdbopen(TCBDB *bdb, const char *path, int omode);
  • bdb — the B+ tree database object, and it's gotta be one that is not opened yet, bestie. Fresh. Unopened. No cap.
  • path — the path of the database file. That's where the data lives, that's its home 🏠
  • omode — the connection mode. Pick your fighter:
    • BDBOWRITER — you're a writer, you get to change stuff ✍️
    • BDBOREADER — you're a reader, look but don't touch 👀
    • If the mode is BDBOWRITER, you can bitwise-or these in too:
      • BDBOCREAT — creates a brand new database if it doesn't already exist ✨
      • BDBOTRUNC — creates a brand new database regardless if one exists (yep, it wipes it, periodt)
      • BDBOTSYNC — every transaction synchronizes updated contents with the device 💾
    • And both BDBOREADER and BDBOWRITER can be added to by bitwise-or with:
      • BDBONOLCK — opens the database file with no file locking at all 🙈
      • BDBOLCKNB — locking is performed without blocking ⏳

If it worked, you get true back. If not, false. That's the vibe check ✅

The function tcbdbclose is the one you call to close a B+ tree database object. Bye bestie 👋

bool tcbdbclose(TCBDB *bdb);
  • bdb — the B+ tree database object.

true if it slayed, false if it didn't.

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. Not a vibe. Close your databases, i am begging 😭

The function tcbdbput is how you store a record into a B+ tree database object.

bool tcbdbput(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
  • bdb — the B+ tree database object, connected as a writer.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value.

true on success, false otherwise. And if a record with the same key already exists in the database? It gets overwritten. Out with the old 💅

The function tcbdbput2 stores a string record into a B+ tree database object. Same energy, string edition 🎀

bool tcbdbput2(TCBDB *bdb, const char *kstr, const char *vstr);
  • bdb — the B+ tree database object, connected as a writer.
  • kstr — the string of the key.
  • vstr — the string of the value.

true if successful, false if not. Same key already there? Overwritten. Simple as that.

The function tcbdbputkeep stores a new record into a B+ tree database object.

bool tcbdbputkeep(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
  • bdb — the B+ tree database object, connected as a writer.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value.

true on success, false otherwise. And if a record with that same key already exists in the database, this function has no effect. It just... doesn't. Nothing happens. It's giving polite decline 🙅‍♀️

The function tcbdbputkeep2 stores a new string record into a B+ tree database object.

bool tcbdbputkeep2(TCBDB *bdb, const char *kstr, const char *vstr);
  • bdb — the B+ tree database object, connected as a writer.
  • kstr — the string of the key.
  • vstr — the string of the value.

true if it worked, false if it didn't. Duplicate key? No effect. Iconic restraint honestly.

The function tcbdbputcat concatenates a value onto the end of the existing record in a B+ tree database object. Gluing vibes 🫶

bool tcbdbputcat(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
  • bdb — the B+ tree database object, connected as a writer.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value.

true on success, false otherwise. And if there's no corresponding record? A new record is created. It's like, "fine, i'll start it myself" 💅

The function tcbdbputcat2 concatenates a string value at the end of the existing record in a B+ tree database object.

bool tcbdbputcat2(TCBDB *bdb, const char *kstr, const char *vstr);
  • bdb — the B+ tree database object, connected as a writer.
  • kstr — the string of the key.
  • vstr — the string of the value.

true if successful, false if not. No corresponding record? New record, created, done ✨

The function tcbdbputdup stores a record into a B+ tree database object, but it allows duplication of keys. Yes, you can have the same key more than once. Chaotic. Love that for us 💜

bool tcbdbputdup(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
  • bdb — the B+ tree database object, connected as a writer.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value.

true on success, false otherwise. If a record with the same key already exists in the database, the new record is placed after the existing one. Queue up, bestie 🚶‍♀️

The function tcbdbputdup2 stores a string record into a B+ tree database object, also allowing duplication of keys.

bool tcbdbputdup2(TCBDB *bdb, const char *kstr, const char *vstr);
  • bdb — the B+ tree database object, connected as a writer.
  • kstr — the string of the key.
  • vstr — the string of the value.

true if successful, false if not. Same key already in there? New record goes after the existing one. No cutting the line 🎀

The function tcbdbputdup3 stores records (plural!!) into a B+ tree database object, allowing duplication of keys. Group drop 🫂

bool tcbdbputdup3(TCBDB *bdb, const void *kbuf, int ksiz, const TCLIST *vals);
  • bdb — the B+ tree database object, connected as a writer.
  • kbuf — pointer to the region of the common key.
  • ksiz — size of the region of the common key.
  • vals — a list object containing values.

true on success, false otherwise. If a record with the same key already exists in the database, the new records are placed after the existing one. The whole friend group gets in line 💅

The function tcbdbout removes a record from a B+ tree database object. Gone. Deleted. Not coming back 🔥

bool tcbdbout(TCBDB *bdb, const void *kbuf, int ksiz);
  • bdb — the B+ tree database object, connected as a writer.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.

true on success, false otherwise. And if you specify the key of duplicated records, the first one is selected. Only the first. Pick your battles ✂️

The function tcbdbout2 removes a string record from a B+ tree database object.

bool tcbdbout2(TCBDB *bdb, const char *kstr);
  • bdb — the B+ tree database object, connected as a writer.
  • kstr — the string of the key.

true if successful, false if not. Duplicated records with that key? The first one is selected. Yeah. Just the first one 😌

The function tcbdbout3 removes records (plural) from a B+ tree database object. Full clear-out energy 🧹

bool tcbdbout3(TCBDB *bdb, const void *kbuf, int ksiz);
  • bdb — the B+ tree database object, connected as a writer.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.

true on success, false otherwise. If the key of duplicated records is specified, all of them are removed. All. Of. Them. No survivors 💀

The function tcbdbget retrieves a record from a B+ tree database object. The reading era 📖

void *tcbdbget(TCBDB *bdb, const void *kbuf, int ksiz, int *sp);
  • bdb — the B+ tree database object.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • sp — pointer to the variable into which the size of the region of the return value is assigned.

If it worked, you get back the pointer to the region of the value of the corresponding record. If there's no record that corresponds, you get NULL. That's it, that's the whole answer 🫥

If the key of duplicated records is specified, the first one is selected.

And here's the cute part: 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. Do not forget this. Free your memory, bestie, or it's giving leak 😭

💖 tcbdbget2 — the string-in, string-out getter 💖

okay bestie, so tcbdbget2 is what you call when you wanna retrieve a string record out of a B+ tree database object. string key in, string value out, zero buffer maths required. it's giving convenience. ✨

char *tcbdbget2(TCBDB *bdb, const char *kstr);
  • bdb — the B+ tree database object. the main character of this whole story, honestly.
  • kstr — the string of the key. like, the lil string that tells the database which record you're after.

If it all goes right, the return value is the string of the value of the corresponding record. and if no record corresponds? you get NULL. that's the whole vibe check. 🙈

🚨 if the key of duplicated records is specified, the first one is selected. only the first. not the whole squad.
💸 and listen, this part matters: the region of the return value is allocated with the malloc call, so it should be released with the free call when it is no longer in use. free your memory, free yourself. 🫶

🦋 tcbdbget3 — get it, but make it volatile 🦋

tcbdbget3 retrieves a record in a B+ tree database object as a volatile buffer. cute, fast, and absolutely not yours to keep. 💅

const void *tcbdbget3(TCBDB *bdb, const void *kbuf, int ksiz, int *sp);
  • bdb — the B+ tree database object.
  • kbuf — the pointer to the region of the key.
  • ksiz — the size of the region of the key.
  • sp — the pointer to the variable into which the size of the region of the return value is assigned. yes, you hand it a pointer and it fills in the size for you. teamwork. 🤝

If successful, the return value is the pointer to the region of the value of the corresponding record. NULL is returned if no record corresponds. same deal as before with duplicated keys — the first one is selected.

Bestie, two things you need to know:

  • an additional zero code is appended at the end of the region of the return value, so the return value can be treated as a character string. convenient! 🎀
  • the region of the return value is volatile and it may be spoiled by another operation of the database. so copy that data into another involatile buffer immediately. like, do not pass go, do not collect $200, do not go get a snack first. 😭

🌈 tcbdbget4 — get all the records 🌈

tcbdbget4 retrieves records in a B+ tree database object — plural, babes. all of them.

TCLIST *tcbdbget4(TCBDB *bdb, const void *kbuf, int ksiz);
  • bdb — the B+ tree database object.
  • kbuf — the pointer to the region of the key.
  • ksiz — the size of the region of the key.

If successful, the return value is a list object of the values of the corresponding records. NULL is returned if no record corresponds. this is the one you want when the key has duplicates and you refuse to pick favourites. 👑

🌸 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. new it up, delete it down. periodt.

🍓 tcbdbvnum — how many records?? 🍓

tcbdbvnum gets the number of records corresponding a key in a B+ tree database object. counting era. 🔢

int tcbdbvnum(TCBDB *bdb, const void *kbuf, int ksiz);
  • bdb — the B+ tree database object.
  • kbuf — the pointer to the region of the key.
  • ksiz — the size of the region of the key.

If successful, the return value is the number of the corresponding records. else, it is 0. so a zero is a "nope, nothing here" — no cap. 💀

🧚 tcbdbvnum2 — the string-key remix 🧚

tcbdbvnum2 does the exact same thing but for a string key. glow up. ✨

int tcbdbvnum2(TCBDB *bdb, const char *kstr);
  • bdb — the B+ tree database object.
  • kstr — the string of the key.

If successful, the return value is the number of the corresponding records, else, it is 0. same energy, stringier fit. 💖

💅 tcbdbvsiz — how big is the value tho 💅

tcbdbvsiz gets the size of the value of a record in a B+ tree database object.

int tcbdbvsiz(TCBDB *bdb, const void *kbuf, int ksiz);
  • bdb — the B+ tree database object.
  • kbuf — the pointer to the region of the key.
  • ksiz — the size of the region of the key.

If successful, the return value is the size of the value of the corresponding record. else, it is -1. so -1 is the "no record, bestie" signal. don't @ me.

If the key of duplicated records is specified, the first one is selected. you already know the rule. 🎀

🫶 tcbdbvsiz2 — size, but string edition 🫶

tcbdbvsiz2 gets the size of the value of a string record in a B+ tree database object.

int tcbdbvsiz2(TCBDB *bdb, const char *kstr);
  • bdb — the B+ tree database object.
  • kstr — the string of the key.

If successful, the return value is the size of the value of the corresponding record, else, it is -1. and yep — if the key of duplicated records is specified, the first one is selected. 💜

🌸 tcbdbrange — the range era 🌸

tcbdbrange gets keys of ranged records in a B+ tree database object. this is the one for "gimme everything between here and there". iconic behaviour.

TCLIST *tcbdbrange(TCBDB *bdb, const void *bkbuf, int bksiz, bool binc, const void *ekbuf, int eksiz, bool einc, int max);
  • bdb — the B+ tree database object.
  • bkbuf — the pointer to the region of the key of the beginning border. if it is NULL, the first record is specified. start from the top, slay.
  • bksiz — the size of the region of the beginning key.
  • binc — whether the beginning border is inclusive or not. are we letting the starting key in the club or not. 🎟️
  • ekbuf — the pointer to the region of the key of the ending border. if it is NULL, the last record is specified.
  • eksiz — the size of the region of the ending key.
  • einc — whether the ending border is inclusive or not.
  • max — the maximum number of keys to be fetched. if it is negative, no limit is specified. unlimited. unhinged. 🔥

The return value is a list object of the keys of the corresponding records. this function does never fail — it returns an empty list even if no record corresponds. so no drama, no NULL, just vibes.

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

🎀 tcbdbrange2 — range, but string keys 🎀

tcbdbrange2 gets string keys of ranged records in a B+ tree database object.

TCLIST *tcbdbrange2(TCBDB *bdb, const char *bkstr, bool binc, const char *ekstr, bool einc, int max);
  • bdb — the B+ tree database object.
  • bkstr — the string of the key of the beginning border. if it is NULL, the first record is specified.
  • binc — whether the beginning border is inclusive or not.
  • ekstr — the string of the key of the ending border. if it is NULL, the last record is specified.
  • einc — whether the ending border is inclusive or not.
  • max — 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 keys of the corresponding records. does never fail. empty list even if no record corresponds. same as its sibling, just stringier. 💅

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

⭐ tcbdbfwmkeys — forward matching keys ⭐

tcbdbfwmkeys gets forward matching keys in a B+ tree database object. you give it a prefix, it gives you every key that starts with that prefix. autocomplete core. 🦋

TCLIST *tcbdbfwmkeys(TCBDB *bdb, const void *pbuf, int psiz, int max);
  • bdb — the B+ tree database object.
  • pbuf — the pointer to the region of the prefix.
  • psiz — the size of the region of the prefix.
  • max — the maximum number of keys to be fetched. if it is negative, no limit is specified. go wild, bestie. 🔥

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.

🌈 tcbdbfwmkeys2 — forward matching string keys 🌈

tcbdbfwmkeys2 gets forward matching string keys in a B+ tree database object.

TCLIST *tcbdbfwmkeys2(TCBDB *bdb, const char *pstr, int max);
  • bdb — the B+ tree database object.
  • pstr — the string of the prefix.
  • max — 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. does never fail. empty list even if no key corresponds. no notes. ✨

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

🔥 tcbdbaddint — math but make it a record 🔥

tcbdbaddint adds an integer to a record in a B+ tree database object. it's giving calculator energy, but the calculator lives in your database. 😭

int tcbdbaddint(TCBDB *bdb, const void *kbuf, int ksiz, int num);
  • bdb — the B+ tree database object connected as a writer. yes, you need write access for this one. read-only girls can't sit with us on this call. 💅
  • kbuf — the pointer to the region of the key.
  • ksiz — the size of the region of the key.
  • num — the additional value. the amount you're adding. the lil number that makes it move. 🔢

If successful, the return value is the summation value. else, it is INT_MIN. that's the "nope" signal, and yes it's dramatic, that's the point.

Here's how it behaves, no cap:

  • 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. so it just... starts one. main character energy. 👑

💜 tcbdbadddouble — and the float version 💜

The function tcbdbadddouble is used in order to add a real number to a record in a B+ tree database object.

…and the tea keeps pouring in the next chunk of this page, bestie 🫖✨

okay bestie, we're back in the API section and the function tour continues 💅 Let's go, no breaks, we're locked in 🔥

  • double tcbdbadddouble(TCBDB *bdb, const void *kbuf, int ksiz, double num); — adds a number to a record, slay
double tcbdbadddouble(TCBDB *bdb, const void *kbuf, int ksiz, double num);
  • bdb — the B+ tree database object, and it has to be connected as a writer, periodt
  • kbuf — pointer to the region of the key
  • ksiz — the size of the region of the key
  • num — the additional value

If it works, you get back the summation value. If it doesn't? You get Not-a-Number 😭 ngl that's the vibe check failing. Here's the tea: if the corresponding record already exists, its value is treated as a real number and num gets added to it. If no record matches, a brand new record holding the additional value gets stored. 🫶

The function tcbdbsync is used in order to synchronize updated contents of a B+ tree database object with the file and the device. (it's giving "save ur work fr fr")

  • bool tcbdbsync(TCBDB *bdb); — sync that database to disk 💾
bool tcbdbsync(TCBDB *bdb);
  • bdb — the B+ tree database object, connected as a writer

Returns true if it went well, false if not. This one is genuinely useful when another process connects to the same database file — iykyk. ✨

The function tcbdboptimize is used in order to optimize the file of a B+ tree database object. (glow-up for ur database)

  • bool tcbdboptimize(TCBDB *bdb, int32_t lmemb, int32_t nmemb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts); — the full database makeover ✨
bool tcbdboptimize(TCBDB *bdb, int32_t lmemb, int32_t nmemb,
int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
  • bdb — the B+ tree database object, connected as a writer
  • lmemb — the number of members in each leaf page. If it's not more than 0, the current setting is not changed
  • nmemb — the number of members in each non-leaf page. If it's not more than 0, the current setting is not changed
  • bnum — the number of elements of the bucket array. If it's not more than 0, the default value is specified. That default is two times of the number of pages
  • apow — the size of record alignment by power of 2. If it's negative, the current setting is not changed
  • fpow — the maximum number of elements of the free block pool by power of 2. If it's negative, the current setting is not changed
  • opts — options by bitwise-or, and there's a whole menu:
    • BDBTLARGE — says the size of the database can be larger than 2GB by using a 64-bit bucket array 💪
    • BDBTDEFLATE — each record is compressed with Deflate encoding
    • BDBTBZIP — each page is compressed with BZIP2 encoding
    • BDBTTCBS — each page is compressed with TCBS encoding
    • and if it's UINT8_MAX, the current setting is not changed

Returns true on success, false otherwise. This function is the one you call to reduce the size of the database file when data fragmentation has happened from successive updating. spring cleaning era 🧹

The function tcbdbvanish is used in order to remove all records of a B+ tree database object. (nuclear option, no going back)

  • bool tcbdbvanish(TCBDB *bdb); — poof, gone, all of it 💀
bool tcbdbvanish(TCBDB *bdb);
  • bdb — the B+ tree database object, connected as a writer

Returns true if it succeeded, false if not. Every record. Gone. Main character energy, honestly. 👑

The function tcbdbcopy is used in order to copy the database file of a B+ tree database object.

  • bool tcbdbcopy(TCBDB *bdb, const char *path); — backup bestie time 🎀
bool tcbdbcopy(TCBDB *bdb, const char *path);
  • bdb — the B+ tree database object
  • path — the path of the destination file. And okay here's the fun part: if it begins with @, the trailing substring is executed as a command line 👀

Returns true if it worked, false if not. And false gets returned if the executed command returns a non-zero code.

Now this is important so listen up: the database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress. So this function is genuinely useful to create a backup file of the database file. safe, sound, slaying ✨

The function tcbdbtranbegin is used in order to begin the transaction of a B+ tree database object.

  • bool tcbdbtranbegin(TCBDB *bdb); — start the transaction 🦋
bool tcbdbtranbegin(TCBDB *bdb);
  • bdb — the B+ tree database object, connected as a writer

Returns true if it went well, false if not.

So the deets: the database is locked by the thread while the transaction is active, so that only one transaction can be activated with a database object at the same time. That means the serializable isolation level is assumed if every database operation is performed in the transaction. And because all pages are cached on memory while the transaction is running, the amount of referred records is limited by the memory capacity. ⚠️ memory check, bestie Also, if the database is closed during the transaction, the transaction is aborted implicitly. No cap.

The function tcbdbtrancommit is used in order to commit the transaction of a B+ tree database object.

  • bool tcbdbtrancommit(TCBDB *bdb); — lock it in, commit it 💅
bool tcbdbtrancommit(TCBDB *bdb);
  • bdb — the B+ tree database object, connected as a writer

Returns true if it worked, false if not. And when it's committed successfully, the update in the transaction is fixed. Periodt. ✨

The function tcbdbtranabort is used in order to abort the transaction of a B+ tree database object.

  • bool tcbdbtranabort(TCBDB *bdb); — nvm, undo that 🙈
bool tcbdbtranabort(TCBDB *bdb);
  • bdb — the B+ tree database object, connected as a writer

Returns true if it worked, false if not. When it's aborted, the update in the transaction is discarded, and the state of the database is rollbacked to before the transaction. like it never happened, iconic

The function tcbdbpath is used in order to get the file path of a B+ tree database object.

  • const char *tcbdbpath(TCBDB *bdb); — where does this thing even live 📂
const char *tcbdbpath(TCBDB *bdb);
  • bdb — the B+ tree database object

The return value is the path of the database file, or NULL if the object does not connect to any database file. (mystery object energy)

The function tcbdbrnum is used in order to get the number of records of a B+ tree database object.

  • uint64_t tcbdbrnum(TCBDB *bdb); — how many records we talking 🔢
uint64_t tcbdbrnum(TCBDB *bdb);
  • bdb — the B+ tree database object

The return value is the number of records, or 0 if the object does not connect to any database file.

The function tcbdbfsiz is used in order to get the size of the database file of a B+ tree database object.

  • uint64_t tcbdbfsiz(TCBDB *bdb); — file size check 📏
uint64_t tcbdbfsiz(TCBDB *bdb);
  • bdb — the B+ tree database object

The return value is the size of the database file, or 0 if the object does not connect to any database file.

The function tcbdbcurnew is used in order to create a cursor object.

  • BDBCUR *tcbdbcurnew(TCBDB *bdb); — new cursor, who dis 🖱️
BDBCUR *tcbdbcurnew(TCBDB *bdb);
  • bdb — the B+ tree database object

The return value is the new cursor object.

⚠️ Listen up fr fr: the cursor is available only after initialization with the tcbdbcurfirst or the tcbdbcurjump functions and so on. And moreover, the position of the cursor will be indefinite when the database is updated after the initialization of the cursor. So don't be surprised bestie. 😭

The function tcbdbcurdel is used in order to delete a cursor object.

  • void tcbdbcurdel(BDBCUR *cur); — bye bye cursor 👋
void tcbdbcurdel(BDBCUR *cur);
  • cur — the cursor object

The function tcbdbcurfirst is used in order to move a cursor object to the first record.

  • bool tcbdbcurfirst(BDBCUR *cur); — jump to the very first record 🥇
bool tcbdbcurfirst(BDBCUR *cur);
  • cur — the cursor object

Returns true if it worked, false if not. And false gets returned if there is no record in the database. (empty database, empty vibes)

The function tcbdbcurlast is used in order to move a cursor object to the last record.

  • bool tcbdbcurlast(BDBCUR *cur); — jump to the very last record 🏁
bool tcbdbcurlast(BDBCUR *cur);
  • cur — the cursor object

Returns true if it worked, false if not. And false gets returned if there is no record in the database.

The function tcbdbcurjump is used in order to move a cursor object to the front of records corresponding a key.

  • bool tcbdbcurjump(BDBCUR *cur, const void *kbuf, int ksiz); — teleport to a key 🎯
bool tcbdbcurjump(BDBCUR *cur, const void *kbuf, int ksiz);
  • cur — the cursor object
  • kbuf — pointer to the region of the key
  • ksiz — the size of the region of the key

Returns true if it worked, false if not. false gets returned if there is no record corresponding the condition.

And here's the lil detail that matters: 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 always finds the closest vibe ✨

The function tcbdbcurjump2 is used in order to move a cursor object to the front of records corresponding a key string.

  • bool tcbdbcurjump2(BDBCUR *cur, const char *kstr); — same teleport, but string edition 🎀
bool tcbdbcurjump2(BDBCUR *cur, const char *kstr);
  • cur — the cursor object
  • kstr — the string of the key

Returns true if it worked, false if not. false gets returned if there is no record corresponding the condition. Just like its sibling, the cursor is set to the first record corresponding the key, or the next substitute if a completely matching record does not exist. 🦋

The function tcbdbcurprev is used in order to move a cursor object to the previous record.

  • bool tcbdbcurprev(BDBCUR *cur); — back it up one record ⬅️
bool tcbdbcurprev(BDBCUR *cur);
  • cur — the cursor object

Returns true if it worked, false if not. false gets returned if there is no previous record.

The function tcbdbcurnext is used in order to move a cursor object to the next record.

  • bool tcbdbcurnext(BDBCUR *cur); — forward one record ➡️
bool tcbdbcurnext(BDBCUR *cur);
  • cur — the cursor object

Returns true if it worked, false if not. false gets returned if there is no next record.

The function tcbdbcurput is used in order to insert a record around a cursor object.

💅 tcbdbcurput 💅

bool tcbdbcurput(BDBCUR *cur, const void *vbuf, int vsiz, int cpmode);
  • cur — the cursor object of a writer connection. Like, you need write access, bestie.
  • vbuf — pointer to the region of the value.
  • vsiz — size of that region.
  • cpmode — detail adjustment, and it’s giving three choices:
    • BDBCPCURRENT — the value of the current record is overwritten.
    • BDBCPBEFORE — the new record is inserted before the current record.
    • BDBCPAFTER — the new record is inserted after the current record.

If it slays, the return value is true; otherwise, it’s false. And false shows up when the cursor is at an invalid position. 😭

After insertion, the cursor is moved to the inserted record. So it follows the new kid. 💫

🫶 tcbdbcurput2 🫶

bool tcbdbcurput2(BDBCUR *cur, const char *vstr, int cpmode);

This one is for inserting a string record around a cursor object.

  • cur — the cursor object of a writer connection.
  • vstr — the string of the value.
  • cpmode — same detail adjustment as above:
    • BDBCPCURRENT — overwrite the current record’s value.
    • BDBCPBEFORE — insert before the current record.
    • BDBCPAFTER — insert after the current record.

If successful, return value is true; else false. false when the cursor is at an invalid position.

After insertion, the cursor is moved to the inserted record. Periodt. ✨

🗑️ tcbdbcurout 🗑️

bool tcbdbcurout(BDBCUR *cur);

This removes the record where a cursor object is. Bye-bye, data!

  • cur — the cursor object of a writer connection.

If successful, the return value is true; else false. false when the cursor is at an invalid position.

After deletion, the cursor is moved to the next record if possible. So it doesn’t just ghost you. 👻

🔑 tcbdbcurkey 🔑

char *tcbdbcurkey(BDBCUR *cur, int *sp);

Gets the key of the record where the cursor object is.

  • cur — the cursor object.
  • 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 key; else it’s NULL. NULL is returned when the cursor is at an invalid position.

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. Don’t leak, bestie! 💧

🔑 tcbdbcurkey2 🔑

char *tcbdbcurkey2(BDBCUR *cur);

Gets the key string of the record where the cursor object is.

  • cur — the cursor object.

If successful, the return value is the string of the key; else it’s NULL. NULL is returned when the cursor is at an invalid position.

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. Memory hygiene is self-care. 🧼

🔑 tcbdbcurkey3 🔑

const char *tcbdbcurkey3(BDBCUR *cur, int *sp);

Gets the key of the record where the cursor object is, as a volatile buffer.

  • cur — the cursor object.
  • 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 key; else it’s NULL. NULL is returned when the cursor is at an invalid position.

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. But because the region of the return value is volatile and it may be spoiled by another operation of the database, the data should be copied into another involatile buffer immediately. Like, copy it NOW, no waiting. 🏃‍♀️💨

💎 tcbdbcurval 💎

char *tcbdbcurval(BDBCUR *cur, int *sp);

Gets the value of the record where the cursor object is.

  • cur — the cursor object.
  • 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 value; else it’s NULL. NULL is returned when the cursor is at an invalid position.

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. Free it, queen. 👑

💎 tcbdbcurval2 💎

char *tcbdbcurval2(BDBCUR *cur);

Gets the value string of the record where the cursor object is.

  • cur — the cursor object.

If successful, the return value is the string of the value; else it’s NULL. NULL is returned when the cursor is at an invalid position.

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. Don’t forget, bestie! 🎀

💎 tcbdbcurval3 💎

const char *tcbdbcurval3(BDBCUR *cur, int *sp);

Gets the value of the record where the cursor object is, as a volatile buffer.

  • cur — the cursor object.
  • 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 value; else it’s NULL. NULL is returned when the cursor is at an invalid position.

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 volatile and it may be spoiled by another operation of the database, the data should be copied into another involatile buffer immediately. Immediately immediately. ⏰

📦 tcbdbcurrec 📦

bool tcbdbcurrec(BDBCUR *cur, TCXSTR *kxstr, TCXSTR *vxstr);

Gets the key and the value of the record where the cursor object is.

  • cur — the cursor object.
  • kxstr — the object into which the key is wrote down.
  • vxstr — the object into which the value is wrote down.

If successful, the return value is true; else it’s false. false is returned when the cursor is at an invalid position. Two for one, iconic. 🌈

✨ SEE ALSO ✨

Signed, sealed, delivered: this whole vibe is from the TCBDB(3) man page, Man Page edition, dated 2012-08-18. Stay iconic, bestie. 💖🦋✨

📦 where this page comes from