TCUTIL(3)

📦

version 1.4.48 · 2 versions

1.4.48 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.4.48 · centos-stream 10, centos-stream 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 TCUTIL 💖

okay bestie, welcome to TCUTIL(3), the utility API from Tokyo Cabinet ✨ — this is the section 3 manual page and it's a long one so buckle up, we're doing this together 🫶

✨ NAME ✨

tcutil — the utility API 💅

🌸 DESCRIPTION 🌸

Okay so. The utility API is a whole set of routines that let you handle records on memory easily. And especially — and I need you to hear me on this — extensible string, array list, hash map, and ordered tree are useful. Like, genuinely iconic. 🦋

To use the utility API, you include tcutil.h and the related standard header files. Usually you write this near the front of a source file:

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

Now, the object lineup, because you need to know who's who 💜

Objects whose type is pointer to TCXSTR are used for extensible string. An extensible string object is created with tcxstrnew and is deleted with tcxstrdel.
Objects whose type is pointer to TCLIST are used for array list. A list object is created with tclistnew and is deleted with tclistdel.
Objects whose type is pointer to TCMAP are used for hash map. A map object is created with tcmapnew and is deleted with tcmapdel.
Objects whose type is pointer to TCTREE are used for ordered tree. A tree object is created with tctreenew and is deleted with tctreedel.

To avoid memory leak, it is important to delete every object when it is no longer in use. Like, this is the main character rule of memory management, no cap. 🔥

🌈 API OF BASIC UTILITIES 🌈

The constant tcversion is the string containing the version information.

extern const char *tcversion;

The variable tcfatalfunc is the pointer to the call back function for handling a fatal error.

extern void (*tcfatalfunc)(const char *);

The argument specifies the error message.
The initial value of this variable is NULL. If the value is NULL, the default function is called when a fatal error occurs.
A fatal error occurs when memory allocation is failed. 😭

The function tcmalloc is used in order to allocate a region on memory.

void *tcmalloc(size_t size);

size specifies the size of the region.
The return value is the pointer to the allocated region.
This function handles failure of memory allocation implicitly. 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. 💅

The function tccalloc is used in order to allocate a nullified region on memory.

void *tccalloc(size_t nmemb, size_t size);

nmemb specifies the number of elements.
size specifies the size of each element.
The return value is the pointer to the allocated nullified region.
This function handles failure of memory allocation implicitly. Because the region of the return value is allocated with the calloc call, it should be released with the free call when it is no longer in use. 🎀

The function tcrealloc is used in order to re-allocate a region on memory.

void *tcrealloc(void *ptr, size_t size);

ptr specifies the pointer to the region.
size specifies the size of the region.
The return value is the pointer to the re-allocated region.
This function handles failure of memory allocation implicitly. Because the region of the return value is allocated with the realloc call, it should be released with the free call when it is no longer in use. ✨

The function tcmemdup is used in order to duplicate a region on memory.

void *tcmemdup(const void *ptr, size_t size);

ptr specifies the pointer to the region.
size specifies the size of the region.
The return value is the pointer to the allocated region of the duplicate.
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. 🫶

The function tcstrdup is used in order to duplicate a string on memory.

char *tcstrdup(const void *str);

str specifies the string.
The return value is the allocated string equivalent to the specified 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. 🌸

The function tcfree is used in order to free a region on memory.

void tcfree(void *ptr);

ptr specifies the pointer to the region. If it is NULL, this function has no effect.
Although this function is just a wrapper of free call, this is useful in applications using another package of the malloc series. 👑

🧚 API OF EXTENSIBLE STRING 🧚

The function tcxstrnew is used in order to create an extensible string object.

TCXSTR *tcxstrnew(void);

The return value is the new extensible string object. 💖

The function tcxstrnew2 is used in order to create an extensible string object from a character string.

TCXSTR *tcxstrnew2(const char *str);

str specifies the string of the initial content.
The return value is the new extensible string object containing the specified string. ✨

The function tcxstrnew3 is used in order to create an extensible string object with the initial allocation size.

TCXSTR *tcxstrnew3(int asiz);

asiz specifies the initial allocation size.
The return value is the new extensible string object. 🎀

The function tcxstrdup is used in order to copy an extensible string object.

TCXSTR *tcxstrdup(const TCXSTR *xstr);

xstr specifies the extensible string object.
The return value is the new extensible string object equivalent to the specified object. 🦋

The function tcxstrdel is used in order to delete an extensible string object.

void tcxstrdel(TCXSTR *xstr);

xstr specifies the extensible string object.
Note that the deleted object and its derivatives can not be used anymore. 💀

The function tcxstrcat is used in order to concatenate a region to the end of an extensible string object.

void tcxstrcat(TCXSTR *xstr, const void *ptr, int size);

xstr specifies the extensible string object.
ptr specifies the pointer to the region to be appended.
size specifies the size of the region. 💜

The function tcxstrcat2 is used in order to concatenate a character string to the end of an extensible string object.

void tcxstrcat2(TCXSTR *xstr, const char *str);

xstr specifies the extensible string object.
str specifies the string to be appended. 🌈

The function tcxstrptr is used in order to get the pointer of the region of an extensible string object.

const void *tcxstrptr(const TCXSTR *xstr);

xstr specifies the extensible string object.
The return value is the pointer of the region of the object.
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. 🫶

The function tcxstrsize is used in order to get the size of the region of an extensible string object.

int tcxstrsize(const TCXSTR *xstr);

xstr specifies the extensible string object.
The return value is the size of the region of the object. 📏

The function tcxstrclear is used in order to clear an extensible string object.

void tcxstrclear(TCXSTR *xstr);

xstr specifies the extensible string object.
The internal buffer of the object is cleared and the size is set zero. ✨

The function tcxstrprintf is used in order to perform formatted output into an extensible string object.

void tcxstrprintf(TCXSTR *xstr, const char *format, ...);

xstr specifies the extensible string object.
format specifies the printf-like format string. The conversion character % can be used with such flag characters as s, d, o, u, x, X, c, e, E, f, g, G, @, ?, b, and %. @ works as with s but escapes meta characters of XML. ? works as with s but escapes meta characters of URL. b converts an integer to the string as binary numbers. The other conversion character work as with each original.
The other arguments are used according to the format string. 💅

The function tcsprintf is used in order to allocate a formatted string on memory.

char *tcsprintf(const char *format, ...);

format specifies the printf-like format string. The conversion character % can be used with such flag characters as s, d, o, u, x, X, c, e, E, f, g, G, @, ?, b, and %. @ works as with s but escapes meta characters of XML. ? works as with s but escapes meta characters of URL. b converts an integer to the string as binary numbers. The other conversion character work as with each original.
The other arguments are used according to the format string.
The return value is the pointer to the region of the result 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. 🔥

🎀 API OF ARRAY LIST 🎀

The function tclistnew is used in order to create a list object.

TCLIST *tclistnew(void);

The return value is the new list object. 💖

The function tclistnew2 is used in order to create a list object with expecting the number of elements.

The function tclistnew2 is your ✨planned ahead✨ list maker — same list energy, but you tell it up front how much stuff you're gonna cram in there.

TCLIST *tclistnew2(int anum);

anum — the number of elements you expect to store in the list. Manifesting capacity, bestie 💅
The return value is the new list object. Shiny, fresh, yours.

Then there's tclistnew3, which is the one you call when you already know your elements and you're just done waiting. It builds a list object with initial string elements, all in one go 🎀

TCLIST *tclistnew3(const char *str, ...);

str — the string of the first element.
The other arguments are other elements. They should be trailed by a NULL argument — yes, the NULL is mandatory, it's the little periodt at the end of your sentence, do not skip it 🙈
The return value is the new list object.

tclistdup is the copy-paste of the list world. Dupe it, bestie 🦋

TCLIST *tclistdup(const TCLIST *list);

list — the list object.
The return value is the new list object equivalent to the specified object. Same vibe, different memory.

tclistdel is the goodbye function. Clean up after yourself, it's giving responsible main character 🌸

void tclistdel(TCLIST *list);

list — the list object.
> ⚠️ Note that the deleted object and its derivatives can not be used anymore. Like, cannot. That pointer is a ghost now, do not touch it 💀

tclistnum tells you how many elements are in the list. The headcount, the roll call, the "how many of us are in this group chat" 📋

int tclistnum(const TCLIST *list);

list — the list object.
The return value is the number of elements of the list.

tclistval hands you the pointer to the region of an element. Not a copy, the actual region — so don't go feral editing it without thinking, iykyk ✨

const void *tclistval(const TCLIST *list, int index, int *sp);

list — the list object.
index — the index of the element.
sp — the pointer to the variable into which the size of the region of the return value is assigned.
The return value is the pointer to the region of the value.
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. Free little bonus byte, slay 💖
If index is equal to or more than the number of elements, the return value is NULL. Out of bounds means nothing for you, bestie 😭

tclistval2 is tclistval but it's the string-forward version, no size variable required 🌈

const char *tclistval2(const TCLIST *list, int index);

list — the list object.
index — the index of the element.
The return value is the string of the value.
If index is equal to or more than the number of elements, the return value is NULL.

tclistpush adds an element at the end of the list. Tail-end girlie, always arriving last but making an entrance 👑

void tclistpush(TCLIST *list, const void *ptr, int size);

list — the list object.
ptr — the pointer to the region of the new element.
size — the size of the region.

tclistpush2 is the string-flavoured push — same end-of-list placement, but you just hand it a string and it handles the rest 🍓

void tclistpush2(TCLIST *list, const char *str);

list — the list object.
str — the string of the new element.

tclistpop yanks the element off the end of the list and gives it to you. Reverse push, it's giving poetic symmetry 💅

void *tclistpop(TCLIST *list, int *sp);

list — the list object.
sp — the pointer to the variable into which the size of the region of the return value is assigned.
The return value is the pointer to the region of the removed element.
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 your pops, bestie, or you're leaking memory and that's not the aesthetic. 😭
If the list is empty, the return value is NULL.

tclistpop2 — same pop, but it gives you a string and saves you a step 🧚

char *tclistpop2(TCLIST *list);

list — the list object.
The return value is the string of the removed element.
> 🚨 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. Same rules, no exceptions.
If the list is empty, the return value is NULL.

tclistunshift adds an element at the top of the list. Front of the line, main character energy, no waiting 💖

void tclistunshift(TCLIST *list, const void *ptr, int size);

list — the list object.
ptr — the pointer to the region of the new element.
size — the size of the region.

tclistunshift2 is the string version of that top-of-list insert 🌸

void tclistunshift2(TCLIST *list, const char *str);

list — the list object.
str — the string of the new element.

tclistshift removes the element at the top of the list and hands it over. Unshift's chaotic twin 🔥

void *tclistshift(TCLIST *list, int *sp);

list — the list object.
sp — the pointer to the variable into which the size of the region of the return value is assigned.
The return value is the pointer to the region of the removed element.
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. You will be freeing this, bestie, I'm watching 👀
If the list is empty, the return value is NULL.

tclistshift2 — string-flavoured shift, top of the list, no size variable, immaculate vibes ✨

char *tclistshift2(TCLIST *list);

list — the list object.
The return value is the string of the removed element.
> 🚨 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.
If the list is empty, the return value is NULL.

tclistinsert slides a new element in at the exact spot you name. Precision, periodt 🎯

void tclistinsert(TCLIST *list, int index, const void *ptr, int size);

list — the list object.
index — the index of the new element.
ptr — the pointer to the region of the new element.
size — the size of the region.
If index is equal to or more than the number of elements, this function has no effect. Nothing happens. It simply does not engage 🙈

tclistinsert2 — same precise insertion, but with a string instead of a pointer-plus-size 🎀

void tclistinsert2(TCLIST *list, int index, const char *str);

list — the list object.
index — the index of the new element.
str — the string of the new element.
If index is equal to or more than the number of elements, this function has no effect.

tclistremove takes out the element at the index you specify and gives it to you. Eviction notice, served 💅

void *tclistremove(TCLIST *list, int index, int *sp);

list — the list object.
index — the index of the element to be removed.
sp — the pointer to the variable into which the size of the region of the return value is assigned.
The return value is the pointer to the region of the removed element.
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.
If index is equal to or more than the number of elements, no element is removed and the return value is NULL.

tclistremove2 — string edition of the index eviction, zero extra variables required 🦋

char *tclistremove2(TCLIST *list, int index);

list — the list object.
index — the index of the element to be removed.
The return value is the string of the removed element.
> 🚨 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.
If index is equal to or more than the number of elements, no element is removed and the return value is NULL.

tclistover doesn't add, doesn't remove — it overwrites whatever's sitting at that index. Glow-up via replacement, lowkey iconic 👑

void tclistover(TCLIST *list, int index, const void *ptr, int size);

list — the list object.
index — the index of the element to be overwritten.
ptr — the pointer to the region of the new content.
size — the size of the new content.
If index is equal to or more than the number of elements, this function has no effect.

tclistover2 is the string-flavoured overwrite. Swap the content, keep the slot 🌈

void tclistover2(TCLIST *list, int index, const char *str);

list — the list object.
index — the index of the element to be overwritten.
str — the string of the new content.
If index is equal to or more than the number of elements, this function has no effect.

And finally (for now 😌), the function tclistsort is used in order to sort elements of a list object in lexical order.

`tclistsort` — sorts a list object 💫

void tclistsort(TCLIST *list);

list specifies the list object.

`tclistlsearch` — finds an element with a linear search 🔎

int tclistlsearch(const TCLIST *list, const void *ptr, int size);

list specifies the list object.
ptr specifies the pointer to the region of the key.
size specifies the size of the region.
The return value is the index of a corresponding element, or -1 if there is no corresponding element.
If two or more elements correspond, the former returns — so you get the first one, no cap.

`tclistbsearch` — finds an element with a binary search ⚡

int tclistbsearch(const TCLIST *list, const void *ptr, int size);

list specifies the list object. It should be sorted in lexical order.
ptr specifies the pointer to the region of the key.
size specifies the size of the region.
The return value is the index of a corresponding element, or -1 if there is no corresponding element.
If two or more elements correspond, which one returns is not defined. So like… don't count on a specific one, bestie, it's giving chaos 🙈

`tclistclear` — wipes a list object clean 🧼

void tclistclear(TCLIST *list);

list specifies the list object.
All elements are removed. Every single one. Gone. 💀

`tclistdump` — serializes a list object into a byte array 📦

void *tclistdump(const TCLIST *list, int *sp);

list specifies the list object.
sp specifies the pointer to the variable into which the size of the region of the return value is assigned.
The return value is the pointer to the region of the result serial region.
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.

🫶 bestie pls do not forget the free. That's a leak and the leak is not the vibe.

`tclistload` — builds a list object back from a serialized byte array 🪄

TCLIST *tclistload(const void *ptr, int size);

ptr specifies the pointer to the region of serialized byte array.
size specifies the size of the region.
The return value is a new list object.
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.

🗺️ API OF HASH MAP 🗺️

okay this is the section where things get actually iconic — key/value maps, aka the data structure of all time ✨

`tcmapnew` — creates a map object 🎀

TCMAP *tcmapnew(void);

The return value is the new map object.

`tcmapnew2` — creates a map object, but you pick how many buckets 🪣

TCMAP *tcmapnew2(uint32_t bnum);

bnum specifies the number of the buckets.
The return value is the new map object.

`tcmapnew3` — creates a map object that's already got string elements in it 🌸

TCMAP *tcmapnew3(const char *str, ...);

str specifies the string of the first element.
The other arguments are other elements. They should be trailed by a NULL argument.
The return value is the new map object.
The key and the value of each record are situated one after the other.

🌈 fr fr remember the trailing NULL — that's how it knows you're done.

`tcmapdup` — copies a map object 👯

TCMAP *tcmapdup(const TCMAP *map);

map specifies the map object.
The return value is the new map object equivalent to the specified object.

`tcmapdel` — deletes a map object 🗑️

void tcmapdel(TCMAP *map);

map specifies the map object.

💀 Note that the deleted object and its derivatives can not be used anymore. Not even a little. Not even to peek. It's over, periodt.

`tcmapput` — stores a record into a map object 💾

void tcmapput(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

map specifies the map object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
vbuf specifies the pointer to the region of the value.
vsiz specifies the size of the region of the value.
If a record with the same key exists in the map, it is overwritten.

`tcmapput2` — stores a string record into a map object ✨

void tcmapput2(TCMAP *map, const char *kstr, const char *vstr);

map specifies the map object.
kstr specifies the string of the key.
vstr specifies the string of the value.
If a record with the same key exists in the map, it is overwritten.

`tcmapputkeep` — stores a new record, and refuses to clobber 🛑

bool tcmapputkeep(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

map specifies the map object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
vbuf specifies the pointer to the region of the value.
vsiz specifies the size of the region of the value.
If successful, the return value is true, else, it is false.
If a record with the same key exists in the map, this function has no effect.

`tcmapputkeep2` — same energy, but with strings 🎀

bool tcmapputkeep2(TCMAP *map, const char *kstr, const char *vstr);

map specifies the map object.
kstr specifies the string of the key.
vstr specifies the string of the value.
If successful, the return value is true, else, it is false.
If a record with the same key exists in the map, this function has no effect.

`tcmapputcat` — glues a value onto the end of an existing value 🧩

void tcmapputcat(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

map specifies the map object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
vbuf specifies the pointer to the region of the value.
vsiz specifies the size of the region of the value.
If there is no corresponding record, a new record is created.

`tcmapputcat2` — glues a string value onto the end of an existing value 🧚

void tcmapputcat2(TCMAP *map, const char *kstr, const char *vstr);

map specifies the map object.
kstr specifies the string of the key.
vstr specifies the string of the value.
If there is no corresponding record, a new record is created.

`tcmapout` — removes a record from a map object ✂️

bool tcmapout(TCMAP *map, const void *kbuf, int ksiz);

map specifies the map object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
If successful, the return value is true. false is returned when no record corresponds to the specified key.

`tcmapout2` — removes a string record from a map object 🍓

bool tcmapout2(TCMAP *map, const char *kstr);

map specifies the map object.
kstr specifies the string of the key.
If successful, the return value is true. false is returned when no record corresponds to the specified key.

`tcmapget` — retrieves a record from a map object 🔍

const void *tcmapget(const TCMAP *map, const void *kbuf, int ksiz, int *sp);

map specifies the map object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
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 value of the corresponding record. NULL is returned when no record corresponds.
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.

👑 that last bit is the good stuff — free null-termination, no extra work, we love a considerate API.

`tcmapget2` — retrieves a string record from a map object 🌟

const char *tcmapget2(const TCMAP *map, const char *kstr);

map specifies the map object.
kstr specifies the string of the key.
If successful, the return value is the string of the value of the corresponding record. NULL is returned when no record corresponds.

`tcmapmove` — moves a record to the edge of a map object 🚀

bool tcmapmove(TCMAP *map, const void *kbuf, int ksiz, bool head);

map specifies the map object.
kbuf specifies the pointer to the region of a key.
ksiz specifies the size of the region of the key.
head specifies the destination which is the head if it is true or the tail if else.
If successful, the return value is true. false is returned when no record corresponds to the specified key.

`tcmapmove2` — moves a string record to the edge of a map object 🦋

The function tcmapmove2 is used in order to move a string record to the edge of a map object.

The function tcmapmove2 is giving "rearrange the lineup" energy — it moves a record to the head or the tail of the map object, bestie.

bool tcmapmove2(TCMAP *map, const char *kstr, bool head);

map specifies the map object.
kstr specifies the string of a key.
head specifies the destination which is the head if it is true or the tail if else.

If it worked, the return value is true. False comes back when no record corresponds to the specified key. 💅

The function tcmapiterinit is used in order to initialize the iterator of a map object.

void tcmapiterinit(TCMAP *map);

map specifies the map object.

The iterator is used in order to access the key of every record stored in the map object. ✨

The function tcmapiternext is used in order to get the next key of the iterator of a map object.

const void *tcmapiternext(TCMAP *map, int *sp);

map specifies the map 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 key, else, it is NULL. NULL is returned when no record can be fetched from 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. The order of iteration is assured to be the same as the stored order. 🦋

The function tcmapiternext2 is used in order to get the next key string of the iterator of a map object.

const char *tcmapiternext2(TCMAP *map);

map specifies the map object.

If successful, the return value is the pointer to the region of the next key, else, it is NULL. NULL is returned when no record can be fetched from the iterator. The order of iteration is assured to be the same as the stored order. 🌸

The function tcmaprnum is used in order to get the number of records stored in a map object.

uint64_t tcmaprnum(const TCMAP *map);

map specifies the map object.

The return value is the number of the records stored in the map object. Counting era, periodt. 🔢

The function tcmapmsiz is used in order to get the total size of memory used in a map object.

uint64_t tcmapmsiz(const TCMAP *map);

map specifies the map object.

The return value is the total size of memory used in a map object. 💾

The function tcmapkeys is used in order to create a list object containing all keys in a map object.

TCLIST *tcmapkeys(const TCMAP *map);

map specifies the map object.

The return value is the new list object containing all keys in the map object. 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. Don't forget the cleanup, bestie, we do not leak in this house. 🎀

The function tcmapvals is used in order to create a list object containing all values in a map object.

TCLIST *tcmapvals(const TCMAP *map);

map specifies the map object.

The return value is the new list object containing all values in the map object. 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. 🫶

The function tcmapaddint is used in order to add an integer to a record in a map object.

int tcmapaddint(TCMAP *map, const void *kbuf, int ksiz, int num);

map specifies the map object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
num specifies the additional value.

The return value is the summation value. 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. It's giving math but make it map energy. ➕

The function tcmapadddouble is used in order to add a real number to a record in a map object.

double tcmapadddouble(TCMAP *map, const void *kbuf, int ksiz,
double num);

map specifies the map object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
num specifies the additional value.

The return value is the summation value. 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. ✨

The function tcmapclear is used in order to clear a map object.

void tcmapclear(TCMAP *map);

map specifies the map object.

All records are removed. Total wipe, no survivors, iconic behavior. 💀

The function tcmapcutfront is used in order to remove front records of a map object.

void tcmapcutfront(TCMAP *map, int num);

map specifies the map object.
num specifies the number of records to be removed.

The function tcmapdump is used in order to serialize a map object into a byte array.

void *tcmapdump(const TCMAP *map, int *sp);

map specifies the map object.
sp specifies the pointer to the variable into which the size of the region of the return value is assigned.

The return value is the pointer to the region of the result serial region. 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. Free it. Free it. 🔥

The function tcmapload is used in order to create a map object from a serialized byte array.

TCMAP *tcmapload(const void *ptr, int size);

ptr specifies the pointer to the region of serialized byte array.
size specifies the size of the region.

The return value is a new map object. 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. 🧚

🌳 API OF ORDERED TREE 🌳

Okay so now we're in tree territory and it is so organized, everything stays in order, main character energy fr fr. 🌲

The function tctreenew is used in order to create a tree object.

TCTREE *tctreenew(void);

The return value is the new tree object. Fresh out the box. 👑

The function tctreenew2 is used in order to create a tree object with specifying the custom comparison function.

TCTREE *tctreenew2(TCCMP cmp, void *cmpop);

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.

The return value is the new tree object. The default comparison function compares keys of two records by lexical order. The functions tccmplexical (default), tccmpdecimal, tccmpint32, and tccmpint64 are built-in. 🦋

The function tctreedup is used in order to copy a tree object.

TCTREE *tctreedup(const TCTREE *tree);

tree specifies the tree object.

The return value is the new tree object equivalent to the specified object. Copy paste but make it legal. ✨

The function tctreedel is used in order to delete a tree object.

void tctreedel(TCTREE *tree);

tree specifies the tree object.

Note that the deleted object and its derivatives can not be used anymore. Not even a little bit. It's gone gone. 💀

The function tctreeput is used in order to store a record into a tree object.

void tctreeput(TCTREE *tree, const void *kbuf, int ksiz, const
void *vbuf, int vsiz);

tree specifies the tree object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
vbuf specifies the pointer to the region of the value.
vsiz specifies the size of the region of the value.

If a record with the same key exists in the tree, it is overwritten. No mercy, it just gets replaced. 💅

The function tctreeput2 is used in order to store a string record into a tree object.

void tctreeput2(TCTREE *tree, const char *kstr, const char
*vstr);

tree specifies the tree object.
kstr specifies the string of the key.
vstr specifies the string of the value.

If a record with the same key exists in the tree, it is overwritten. Same deal, same energy. 🌸

The function tctreeputkeep is used in order to store a new record into a tree object.

bool tctreeputkeep(TCTREE *tree, const void *kbuf, int ksiz,
const void *vbuf, int vsiz);

tree specifies the tree object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
vbuf specifies the pointer to the region of the value.
vsiz specifies the size of the region of the value.

If successful, the return value is true, else, it is false. If a record with the same key exists in the tree, this function has no effect. It's the respectful one, it does not touch what's already there. 🙈

The function tctreeputkeep2 is used in order to store a new string record into a tree object.

bool tctreeputkeep2(TCTREE *tree, const char *kstr, const char *vstr);

tree specifies the tree object.
kstr specifies the string of the key.
vstr specifies the string of the value.
If successful, the return value is true, else, it is false.
If a record with the same key exists in the tree, this function has no effect.

Okay so this one is the "bestie, if it's already there I'm literally not touching it" version — no overwrite, no drama, just vibes. ✨

The function tctreeputcat is used in order to concatenate a value at the end of the value of the existing record in a tree object.

void tctreeputcat(TCTREE *tree, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

tree specifies the tree object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
vbuf specifies the pointer to the region of the value.
vsiz specifies the size of the region of the value.
If there is no corresponding record, a new record is created.

Concatenate = gluing the new value onto the end of the old one, like adding a lil sticker to the bottom of a note. 🎀

The function tctreeputcat2 is used in order to concatenate a string value at the end of the value of the existing record in a tree object.

void tctreeputcat2(TCTREE *tree, const char *kstr, const char *vstr);

tree specifies the tree object.
kstr specifies the string of the key.
vstr specifies the string of the value.
If there is no corresponding record, a new record is created.

The function tctreeout is used in order to remove a record of a tree object.

bool tctreeout(TCTREE *tree, const void *kbuf, int ksiz);

tree specifies the tree object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
If successful, the return value is true. false is returned when no record corresponds to the specified key.

The function tctreeout2 is used in order to remove a string record of a tree object.

bool tctreeout2(TCTREE *tree, const char *kstr);

tree specifies the tree object.
kstr specifies the string of the key.
If successful, the return value is true. false is returned when no record corresponds to the specified key.

It's giving eviction notice but make it binary — true means it's gone, false means bestie there was never anything there. 💀

The function tctreeget is used in order to retrieve a record in a tree object.

const void *tctreeget(TCTREE *tree, const void *kbuf, int ksiz, int *sp);

tree specifies the tree object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
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 value of the corresponding record. NULL is returned when no record corresponds.
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.

Note the extra zero code at the end — that's your free '\0', so you can literally just treat the returned value as a C string. No cap. 🫶

The function tctreeget2 is used in order to retrieve a string record in a tree object.

const char *tctreeget2(TCTREE *tree, const char *kstr);

tree specifies the tree object.
kstr specifies the string of the key.
If successful, the return value is the string of the value of the corresponding record. NULL is returned when no record corresponds.

The function tctreeiterinit is used in order to initialize the iterator of a tree object.

void tctreeiterinit(TCTREE *tree);

tree specifies the tree object.
The iterator is used in order to access the key of every record stored in the tree object.

Bestie you have to init before you next, that's the whole ritual, don't skip it. 🧚

The function tctreeiternext is used in order to get the next key of the iterator of a tree object.

const void *tctreeiternext(TCTREE *tree, int *sp);

tree specifies the tree 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 key, else, it is NULL. NULL is returned when no record can be fetched from 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.
The order of iteration is assured to be ascending of the keys.

The order is ascending, periodt. You will never get a chaotic random shuffle here — keys come out in order, every single time. 👑

The function tctreeiternext2 is used in order to get the next key string of the iterator of a tree object.

const char *tctreeiternext2(TCTREE *tree);

tree specifies the tree object.
If successful, the return value is the pointer to the region of the next key, else, it is NULL. NULL is returned when no record can be fetched from the iterator.
The order of iteration is assured to be ascending of the keys.

The function tctreernum is used in order to get the number of records stored in a tree object.

uint64_t tctreernum(const TCTREE *tree);

tree specifies the tree object.
The return value is the number of the records stored in the tree object.

The function tctreemsiz is used in order to get the total size of memory used in a tree object.

uint64_t tctreemsiz(const TCTREE *tree);

tree specifies the tree object.
The return value is the total size of memory used in a tree object.

The function tctreekeys is used in order to create a list object containing all keys in a tree object.

TCLIST *tctreekeys(const TCTREE *tree);

tree specifies the tree object.
The return value is the new list object containing all keys in the tree object.
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.

Cleanup check!! This list is yours now — tclistdel it when you're done or it just sits there haunting your heap. 🙈

The function tctreevals is used in order to create a list object containing all values in a tree object.

TCLIST *tctreevals(const TCTREE *tree);

tree specifies the tree object.
The return value is the new list object containing all values in the tree object.
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.

Same deal, bestie — new list, new responsibility. Free it with tclistdel. 💅

The function tctreeaddint is used in order to add an integer to a record in a tree object.

int tctreeaddint(TCTREE *tree, const void *kbuf, int ksiz, int num);

tree specifies the tree object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
num specifies the additional value.
The return value is the summation value.
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.

It's a counter, it's a tally, it's math happening inside your tree. 🔥

The function tctreeadddouble is used in order to add a real number to a record in a tree object.

double tctreeadddouble(TCTREE *tree, const void *kbuf, int ksiz, double num);

tree specifies the tree object.
kbuf specifies the pointer to the region of the key.
ksiz specifies the size of the region of the key.
num specifies the additional value.
The return value is the summation value.
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.

The function tctreeclear is used in order to clear a tree object.

void tctreeclear(TCTREE *tree);

tree specifies the tree object.
All records are removed.

All of them. Every last one. It's giving factory reset. 😭

The function tctreecutfringe is used in order to remove fringe records of a tree object.

void tctreecutfringe(TCTREE *tree, int num);

tree specifies the tree object.
num specifies the number of records to be removed.

The function tctreedump is used in order to serialize a tree object into a byte array.

void *tctreedump(const TCTREE *tree, int *sp);

tree specifies the tree object.
sp specifies the pointer to the variable into which the size of the region of the return value is assigned.
The return value is the pointer to the region of the result serial region.
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.

Important!! malloc gave it to you, so free has to take it back. That's the deal. Don't ghost your allocated memory. 💀

The function tctreeload is used in order to create a tree object from a serialized byte array.

TCTREE *tctreeload(const void *ptr, int size, TCCMP cmp, void *cmpop);

ptr specifies the pointer to the region of serialized byte array.
size specifies the size of the region.
cmp specifies the pointer to the custom comparison function.
cmpop specifies an arbitrary pointer to be given as a parameter of the comparison function. If it is not needed, NULL can be specified.
The return value is a new tree object.
Because the object of the return value is created with the function tctreenew, it should be deleted with the function tctreedel when it is no longer in use.

So tctreedump writes the tree out, and tctreeload brings it right back like nothing ever happened. Serialization glow-up. ✨ And yeah — tctreedel it when you're finished with it, always. 🫶

🌸 API OF ON-MEMORY HASH DATABASE 🌸

The function tcmdbnew is used in order to create an on-memory hash database object.

TCMDB *tcmdbnew(void);

The return value is the new on-memory hash database object.
The object can be shared by plural threads because of the internal mutex.

Thread-safe because of the internal mutex — so multiple threads can all be besties with the same database object and nobody's stepping on anybody. 👑💖

tcmdbnew2 — makes you a fresh on-memory hash database object, but this time you get to say how many buckets it has. Queen behaviour, honestly.

TCMDB *tcmdbnew2(uint32_t bnum);

bnum — the number of buckets. that's it, that's the whole vibe.
the return value is the new on-memory hash database object. ✨
the object can be shared by plural threads because of the internal mutex — so yes bestie, it's thread-safe, go off 🫶

tcmdbdel — yeets an on-memory hash database object into the void. it's gone, it's over, no cap.

void tcmdbdel(TCMDB *mdb);

mdb — the on-memory hash database object. (say bye 💅)

tcmdbput — stores a record into an on-memory hash database object.

void tcmdbput(TCMDB *mdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

mdb — the on-memory hash database object.
kbuf — the pointer to the region of the key.
ksiz — the size of the region of the key.
vbuf — the pointer to the region of the value.
vsiz — the size of the region of the value.
if a record with the same key already exists in the database, it is overwritten. not a merge, not a chat, just overwritten. periodt.

tcmdbput2 — same energy as above but for a string record. cute, effortless, string-coded.

void tcmdbput2(TCMDB *mdb, const char *kstr, const char *vstr);

mdb — the on-memory hash database object.
kstr — the string of the key.
vstr — the string of the value.
if a record with the same key exists in the database, it is overwritten. same rule, same drama.

tcmdbputkeep — stores a new record and refuses to touch anything that's already there. it's giving "respectfully, i'm not doing that" 😌

bool tcmdbputkeep(TCMDB *mdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

mdb — the on-memory hash database object.
kbuf — the pointer to the region of the key.
ksiz — the size of the region of the key.
vbuf — the pointer to the region of the value.
vsiz — the size of the region of 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 function has no effect. literally nothing happens. it just stands there, gorgeous, doing zero.

tcmdbputkeep2 — the string version of the above. stores a new string record, keeps its hands to itself.

bool tcmdbputkeep2(TCMDB *mdb, const char *kstr, const char *vstr);

mdb — the on-memory hash database object.
kstr — the string of the key.
vstr — the string of 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 function has no effect. we stay unbothered.

tcmdbputcat — glues your value onto the end of whatever record is already there. it's the "…and another thing" of database functions 🔥

void tcmdbputcat(TCMDB *mdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

mdb — the on-memory hash database object.
kbuf — the pointer to the region of the key.
ksiz — the size of the region of the key.
vbuf — the pointer to the region of the value.
vsiz — the size of the region of the value.
if there is no corresponding record, a new record is created. so it never ghosts you, it just starts fresh. 🦋

tcmdbputcat2 — the string edition. concatenates a string at the end of the existing record.

void tcmdbputcat2(TCMDB *mdb, const char *kstr, const char *vstr);

mdb — the on-memory hash database object.
kstr — the string of the key.
vstr — the string of the value.
if there is no corresponding record, a new record is created. again, no abandonment here.

tcmdbout — removes a record from an on-memory hash database object. the block button, essentially.

bool tcmdbout(TCMDB *mdb, const void *kbuf, int ksiz);

mdb — the on-memory hash 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 true. false is returned when no record corresponds to the specified key — i.e. there was nothing there to remove, awkward 💀

tcmdbout2 — removes a string record from an on-memory hash database object.

bool tcmdbout2(TCMDB *mdb, const char *kstr);

mdb — the on-memory hash database object.
kstr — the string of the key.
if successful, the return value is true. false is returned when no record corresponds to the specified key. same deal, same energy.

tcmdbget — retrieves a record. the main character function, honestly 👑

void *tcmdbget(TCMDB *mdb, const void *kbuf, int ksiz, int *sp);

mdb — the on-memory hash 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.
if successful, the return value is the pointer to the region of the value of the corresponding record. NULL is returned when no record corresponds. 🫠
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. cute lil bonus.
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 one bestie, that's a leak 😭

tcmdbget2 — retrieves a string record. same function, string-coded entrance.

char *tcmdbget2(TCMDB *mdb, const char *kstr);

mdb — the on-memory hash database object.
kstr — the string of the key.
if successful, the return value is the string of the value of the corresponding record. NULL is returned when no record corresponds.
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. again. free it. i'm not asking twice, i'm asking once but louder. 💅

tcmdbvsiz — tells you how big the value of a record is, without actually handing you the value. it's giving "i'm not showing you the text but i'll tell you how long it is" 🙈

int tcmdbvsiz(TCMDB *mdb, const void *kbuf, int ksiz);

mdb — the on-memory hash 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.

tcmdbvsiz2 — the string-record version of the size check.

int tcmdbvsiz2(TCMDB *mdb, const char *kstr);

mdb — the on-memory hash 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.

tcmdbiterinit — sets up the iterator for an on-memory hash database object. think of it as hitting "start" on the slideshow of every key in there.

void tcmdbiterinit(TCMDB *mdb);

mdb — the on-memory hash database object.
the iterator is used in order to access the key of every record stored in the on-memory hash database. every single one. no skipping. 🎀

tcmdbiternext — grabs the next key off the iterator. one at a time, bestie, we're not greedy.

void *tcmdbiternext(TCMDB *mdb, int *sp);

mdb — the on-memory hash database object.
sp — 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 key, else, it is NULL. NULL is returned when no record can be fetched from the iterator. so NULL = we're done here, thank u next. ✨
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. yes. again. free. every time. 🧚
the order of iteration is assured to be the same as the stored order. so it's consistent, it's reliable, it's lowkey iconic.

tcmdbiternext2 — same as above but it hands you the next key as a string. the easy-mode entrance.

char *tcmdbiternext2(TCMDB *mdb);

mdb — the on-memory hash database object.
if successful, the return value is the pointer to the region of the next key, else, it is NULL. NULL is returned when no record can be fetched from 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. (you know the drill by now 💜)
the order of iteration is assured to be the same as the stored order.

tcmdbfwmkeys — gets you the forward matching keys in an on-memory hash database object. prefix squad, rise 🌈

TCLIST *tcmdbfwmkeys(TCMDB *mdb, const void *pbuf, int psiz, int max);

TCLIST *tcmdbfwmkeys(TCMDB *mdb, const void *pbuf, int psiz, int max);
- mdb — the on-memory hash database object, bestie.
- pbuf — pointer to the region of the prefix.
- psiz — size of the region of the prefix.
- max — the maximum number of keys to be fetched. If it's negative, no limit is specified, go wild.
- What you get back is a list object of the corresponding keys. This function does never fail. Even if no key corresponds, you get an empty list, no drama.
- 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, it's giving basic hygiene 💅
- > Heads up: this function may be very slow because every key in the database is scanned. Like, scanning every single key. It's giving "going through your entire camera roll for one pic" energy 😭

The function tcmdbfwmkeys2 is used in order to get forward matching string keys in an on-memory hash database object.

TCLIST *tcmdbfwmkeys2(TCMDB *mdb, const char *pstr, int max);
- mdb — the on-memory hash 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. 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.
- > And again: this function may be very slow because every key in the database is scanned. Same vibe, same warning, no cap 🐢

The function tcmdbrnum is used in order to get the number of records stored in an on-memory hash database object.

uint64_t tcmdbrnum(TCMDB *mdb);
- mdb — the on-memory hash database object.
- The return value is the number of the records stored in the database. That's it, that's the whole function 🫶

The function tcmdbmsiz is used in order to get the total size of memory used in an on-memory hash database object.

uint64_t tcmdbmsiz(TCMDB *mdb);
- mdb — the on-memory hash database object.
- The return value is the total size of memory used in the database. The receipts on how much RAM this thing is eating 💸

The function tcmdbaddint is used in order to add an integer to a record in an on-memory hash database object.

int tcmdbaddint(TCMDB *mdb, const void *kbuf, int ksiz, int num);
- mdb — the on-memory hash database object.
- kbuf — pointer to the region of the key.
- ksiz — size of the region of the key.
- num — the additional value.
- The return value is the summation value.
- 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. Math o'clock ✨

The function tcmdbadddouble is used in order to add a real number to a record in an on-memory hash database object.

double tcmdbadddouble(TCMDB *mdb, const void *kbuf, int ksiz, double num);
- mdb — the on-memory hash database object.
- kbuf — pointer to the region of the key.
- ksiz — size of the region of the key.
- num — the additional value.
- The return value is the summation value.
- 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. Floating point girlies, this one's for you 🌸

The function tcmdbvanish is used in order to clear an on-memory hash database object.

void tcmdbvanish(TCMDB *mdb);
- mdb — the on-memory hash database object.
- All records are removed. Poof. Gone. Nothing left but vibes 💀

The function tcmdbcutfront is used in order to remove front records of an on-memory hash database object.

void tcmdbcutfront(TCMDB *mdb, int num);
- mdb — the on-memory hash database object.
- num — the number of records to be removed.

🌳 API OF ON-MEMORY TREE DATABASE 🌳

The function tcndbnew is used in order to create an on-memory tree database object.

TCNDB *tcndbnew(void);
- The return value is the new on-memory tree database object.
- The object can be shared by plural threads because of the internal mutex. Thread-safe and thriving, we love to see it 🔥

The function tcndbnew2 is used in order to create an on-memory tree database object with specifying the custom comparison function.

TCNDB *tcndbnew2(TCCMP cmp, void *cmpop);
- cmp — pointer to the custom comparison function.
- cmpop — an arbitrary pointer to be given as a parameter of the comparison function. If it is not needed, NULL can be specified.
- The return value is the new on-memory tree database object.
- The default comparison function compares keys of two records by lexical order. The functions tccmplexical (default), tccmpdecimal, tccmpint32, and tccmpint64 are built-in. Pick your fighter 🎀
- The object can be shared by plural threads because of the internal mutex.

The function tcndbdel is used in order to delete an on-memory tree database object.

void tcndbdel(TCNDB *ndb);
- ndb — the on-memory tree database object.

The function tcndbput is used in order to store a record into an on-memory tree database object.

void tcndbput(TCNDB *ndb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- ndb — the on-memory tree database object.
- 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.
- If a record with the same key exists in the database, it is overwritten. Sorry not sorry, it's replaceable 💅

The function tcndbput2 is used in order to store a string record into an on-memory tree database object.

void tcndbput2(TCNDB *ndb, const char *kstr, const char *vstr);
- ndb — the on-memory tree database object.
- kstr — the string of the key.
- vstr — the string of the value.
- If a record with the same key exists in the database, it is overwritten.

The function tcndbputkeep is used in order to store a new record into an on-memory tree database object.

bool tcndbputkeep(TCNDB *ndb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- ndb — the on-memory tree database object.
- 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.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, this function has no effect. It's giving "I'm not touching that, that's taken" energy 🙈

The function tcndbputkeep2 is used in order to store a new string record into an on-memory tree database object.

bool tcndbputkeep2(TCNDB *ndb, const char *kstr, const char *vstr);
- ndb — the on-memory tree database object.
- kstr — the string of the key.
- vstr — the string of 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 function has no effect.

The function tcndbputcat is used in order to concatenate a value at the end of the existing record in an on-memory tree database.

void tcndbputcat(TCNDB *ndb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- ndb — the on-memory tree database object.
- 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.
- If there is no corresponding record, a new record is created. So either way you're getting a record, bestie 🦋

The function tcndbputcat2 is used in order to concatenate a string at the end of the existing record in an on-memory tree database.

void tcndbputcat2(TCNDB *ndb, const char *kstr, const char *vstr);
- ndb — the on-memory tree database object.
- kstr — the string of the key.
- vstr — the string of the value.
- If there is no corresponding record, a new record is created.

The function tcndbout is used in order to remove a record of an on-memory tree database object.

bool tcndbout(TCNDB *ndb, const void *kbuf, int ksiz);
- ndb — the on-memory tree database object.
- kbuf — pointer to the region of the key.
- ksiz — size of the region of the key.
- If successful, the return value is true. False is returned when no record corresponds to the specified key. Blocked and deleted ✨

The function tcndbout2 is used in order to remove a string record of an on-memory tree database object.

bool tcndbout2(TCNDB *ndb, const char *kstr);
- ndb — the on-memory tree database object.
- kstr — the string of the key.
- If successful, the return value is true. False is returned when no record corresponds to the specified key.

The function tcndbget is used in order to retrieve a record in an on-memory tree database object.

`tcndbget`

void *tcndbget(TCNDB *ndb, const void *kbuf, int ksiz, int *sp);

ndb — the on-memory tree database object, bestie. the one we're vibing with.
kbuf — pointer to the region of the key.
ksiz — size of the region of the key.
sp — pointer to the variable where the size of the region of the return value gets assigned.

If it hits, the return value is a pointer to the region of the value of the record that matches. When nothing matches, you get NULL back. 💀

And okay, cute detail: an extra zero code gets appended at the end of the return value's region, so you can literally treat it as a character string. ✨ But because that region was allocated with the malloc call, you have to release it with the free call once you're done with it. no cap, don't leak.

`tcndbget2`

So tcndbget2 is the one you call when you want to retrieve a string record in an on-memory tree database object. 🎀

char *tcndbget2(TCNDB *ndb, const char *kstr);

ndb — the on-memory tree database object.
kstr — the string of the key.

If it works out, the return value is the string of the value of the corresponding record. No record? NULL. simple as that.

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

`tcndbvsiz`

tcndbvsiz is your girl for getting the size of the value of a record in an on-memory tree database object.

int tcndbvsiz(TCNDB *ndb, const void *kbuf, int ksiz);

ndb — the on-memory tree database object.
kbuf — pointer to the region of the key.
ksiz — size of the region of the key.

If it succeeds, the return value is the size of the value of the corresponding record. Otherwise? -1. 😭

`tcndbvsiz2`

And tcndbvsiz2 does that same thing but for the value of a string record in an on-memory tree database object.

int tcndbvsiz2(TCNDB *ndb, const char *kstr);

ndb — the on-memory 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. 🦋

`tcndbiterinit`

tcndbiterinit initializes the iterator of an on-memory tree database object. 🧚

void tcndbiterinit(TCNDB *ndb);

ndb — the on-memory tree database object.

The iterator is used in order to access the key of every record stored in the on-memory database. like, all of them. one by one. iconic behavior honestly.

`tcndbiternext`

tcndbiternext grabs you the next key of the iterator of an on-memory tree database object. ✨

void *tcndbiternext(TCNDB *ndb, int *sp);

ndb — the on-memory tree database object.
sp — pointer to the variable where the size of the region of the return value gets assigned.

If successful, the return value is the pointer to the region of the next key, else, it is NULL. And NULL shows up specifically when no record can be fetched from the iterator, so don't panic — that's just the end. 🙈

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. The order of iteration is assured to be the same as the stored order. 🔥

`tcndbiternext2`

tcndbiternext2 is the string-flavored twin — it gets the next key string of the iterator of an on-memory tree database object.

char *tcndbiternext2(TCNDB *ndb);

ndb — the on-memory tree database object.

If successful, the return value is the pointer to the region of the next key, else, it is NULL. NULL is returned when no record can be fetched from 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. The order of iteration is assured to be the same as the stored order. 💜

`tcndbfwmkeys`

tcndbfwmkeys gets forward matching keys in an on-memory tree database object. 🍓

TCLIST *tcndbfwmkeys(TCNDB *ndb, const void *pbuf, int psiz, int max);

ndb — the on-memory tree database object.
pbuf — pointer to the region of the prefix.
psiz — size of the region 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. And listen — this function does never fail. it returns an empty list even if no key corresponds. so chill. 😌

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.

`tcndbfwmkeys2`

tcndbfwmkeys2 is the string version — forward matching string keys in an on-memory tree database object.

TCLIST *tcndbfwmkeys2(TCNDB *ndb, const char *pstr, int max);

ndb — the on-memory 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. 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.

`tcndbrnum`

tcndbrnum counts the records stored in an on-memory tree database object. 🎀

uint64_t tcndbrnum(TCNDB *ndb);

ndb — the on-memory tree database object.

The return value is the number of the records stored in the database.

`tcndbmsiz`

tcndbmsiz tells you the total size of memory used in an on-memory tree database object. 🌸

uint64_t tcndbmsiz(TCNDB *ndb);

ndb — the on-memory tree database object.

The return value is the total size of memory used in the database.

`tcndbaddint`

tcndbaddint adds an integer to a record in an on-memory tree database object. 🌈

int tcndbaddint(TCNDB *ndb, const void *kbuf, int ksiz, int num);

ndb — the on-memory tree database object.
kbuf — pointer to the region of the key.
ksiz — size of the region of the key.
num — the additional value.

`tcndbadddouble`

tcndbadddouble is the same energy but for adding a real number to a record in an on-memory tree database object.

double tcndbadddouble(TCNDB *ndb, const void *kbuf, int ksiz, double num);

ndb — the on-memory tree database object.
kbuf — pointer to the region of the key.
ksiz — size of the region of the key.
num — the additional value.

`tcndbvanish`

tcndbvanish clears an on-memory tree database object. 💀

void tcndbvanish(TCNDB *ndb);

ndb — the on-memory tree database object.

All records are removed. all of them. gone. periodt.

`tcndbcutfringe`

tcndbcutfringe removes fringe records of an on-memory tree database object. 🫶

void tcndbcutfringe(TCNDB *ndb, int num);

ndb — the on-memory tree database object.
num — the number of records to be removed.

✨ API OF MEMORY POOL ✨

okay bestie, it's memory pool o'clock 💖 this is the part where you make a whole cleanup crew so you don't have to manually free every little thing. It's giving organized. No cap.

`tcmpoolnew` — new pool, who dis 🌸

This function is used in order to create a memory pool object. Slay, now you have a pool. ✨

TCMPOOL *tcmpoolnew(void);

The return value is the new memory pool object.

`tcmpooldel` — bye bye pool 👋

This function is used in order to delete a memory pool object. It's literally the opposite of new. 💀

void tcmpooldel(TCMPOOL *mpool);

mpool specifies the memory pool object.

Note that the deleted object and its derivatives can not be used anymore. Like, do not touch. Periodt.

`tcmpoolpush` — relegate an arbitrary object to the pool 🫶

This function is used in order to relegate an arbitrary object to a memory pool object. It's basically adopting an object into the pool family. 🏡✨

void *tcmpoolpush(TCMPOOL *mpool, void *ptr, void (*del)(void *));

mpool specifies the memory pool object.
ptr specifies the pointer to the object to be relegated. If it is NULL, this function has no effect.
del specifies the pointer to the function to delete the object.
The return value is the pointer to the given object.
This function assures that the specified object is deleted when the memory pool object is deleted.

`tcmpoolpushptr` — relegate an allocated region 🧚

This function is used in order to relegate an allocated region to a memory pool object. Lowkey iconic.

void *tcmpoolpushptr(TCMPOOL *mpool, void *ptr);

mpool specifies the memory pool object.
ptr specifies the pointer to the region to be relegated. If it is NULL, this function has no effect.
The return value is the pointer to the given object.
This function assures that the specified region is released when the memory pool object is deleted.

`tcmpoolpushxstr` — relegate an extensible string object 🎀

This function is used in order to relegate an extensible string object to a memory pool object. String bestie, you're in the pool now. 🫶

TCXSTR *tcmpoolpushxstr(TCMPOOL *mpool, TCXSTR *xstr);

mpool specifies the memory pool object.
xstr specifies the extensible string object. If it is NULL, this function has no effect.
The return value is the pointer to the given object.
This function assures that the specified object is deleted when the memory pool object is deleted.

`tcmpoolpushlist` — relegate a list object 🦋

This function is used in order to relegate a list object to a memory pool object. List, you're safe now. ✨

TCLIST *tcmpoolpushlist(TCMPOOL *mpool, TCLIST *list);

mpool specifies the memory pool object.
list specifies the list object. If it is NULL, this function has no effect.
The return value is the pointer to the given object.
This function assures that the specified object is deleted when the memory pool object is deleted.

`tcmpoolpushmap` — relegate a map object 🗺️

This function is used in order to relegate a map object to a memory pool object. Map it out, bestie. 💅

TCMAP *tcmpoolpushmap(TCMPOOL *mpool, TCMAP *map);

mpool specifies the memory pool object.
map specifies the map object. If it is NULL, this function has no effect.
The return value is the pointer to the given object.
This function assures that the specified object is deleted when the memory pool object is deleted.

`tcmpoolpushtree` — relegate a tree object 🌳

This function is used in order to relegate a tree object to a memory pool object. Tree, you're rooted in the pool now. 🌲

TCTREE *tcmpoolpushtree(TCMPOOL *mpool, TCTREE *tree);

mpool specifies the memory pool object.
tree specifies the tree object. If it is NULL, this function has no effect.
The return value is the pointer to the given object.
This function assures that the specified object is deleted when the memory pool object is deleted.

`tcmpoolmalloc` — allocate a region relegated to the pool 💅

This function is used in order to allocate a region relegated to a memory pool object. Get that memory, bestie. ✨

void *tcmpoolmalloc(TCMPOOL *mpool, size_t size);

mpool specifies the memory pool object.
The return value is the pointer to the allocated region under the memory pool.

`tcmpoolxstrnew` — new extensible string, but make it pool 💖

This function is used in order to create an extensible string object relegated to a memory pool object.

TCXSTR *tcmpoolxstrnew(TCMPOOL *mpool);

The return value is the new extensible string object under the memory pool.

`tcmpoollistnew` — new list, pool edition 📝

This function is used in order to create a list object relegated to a memory pool object.

TCLIST *tcmpoollistnew(TCMPOOL *mpool);

The return value is the new list object under the memory pool.

`tcmpoolmapnew` — new map, pool edition 🗺️

This function is used in order to create a map object relegated to a memory pool object.

TCMAP *tcmpoolmapnew(TCMPOOL *mpool);

The return value is the new map object under the memory pool.

`tcmpooltreenew` — new tree, pool edition 🌲

This function is used in order to create a tree object relegated to a memory pool object.

TCTREE *tcmpooltreenew(TCMPOOL *mpool);

The return value is the new tree object under the memory pool.

`tcmpoolpop` — pop the most recent cleanup handler 🫧

This function is used in order to remove the most recently installed cleanup handler of a memory pool object. Pop off, literally. 💅

void tcmpoolpop(TCMPOOL *mpool, bool exe);

mpool specifies the memory pool object.
exe specifies whether to execute the destructor of the removed handler.

`tcmpoolclear` — clear all the cleanup handlers 🧼

This function is used in order to remove all cleanup handler of a memory pool object. Clean slate energy. ✨

void tcmpoolclear(TCMPOOL *mpool, bool exe);

mpool specifies the memory pool object.
exe specifies whether to execute the destructors of the removed handlers.

`tcmpoolglobal` — the global memory pool, the main character 👑

This function is used in order to get the global memory pool object. Main character energy, fr fr.

TCMPOOL *tcmpoolglobal(void);

The return value is the global memory pool object.
The global memory pool object is a singleton and assured to be deleted when the process is terminating normally.

🌈 API OF MISCELLANEOUS UTILITIES 🌈

Now we're in the miscellaneous section, bestie. These are the little helper functions that don't fit anywhere else, and honestly? They ate. ✨

`tclmax` — bigger of two integers 🔼

This function is used in order to get the larger value of two integers. Bigger is better, lowkey.

long tclmax(long a, long b);

a specifies an integer.
b specifies the other integer.
The return value is the larger value of the two.

`tclmin` — lesser of two integers 🔽

This function is used in order to get the lesser value of two integers. Smaller, but still iconic.

long tclmin(long a, long b);

a specifies an integer.
b specifies the other integer.
The return value is the lesser value of the two.

`tclrand` — random unsigned long, uniform distribution 🎲

This function is used in order to get a random number as long integer based on uniform distribution. Randomness? Obsessed.

unsigned long tclrand(void);

The return value is the random number between 0 and ULONG_MAX.
This function uses the random number source device and generates a real random number if possible.

`tcdrand` — random double, uniform distribution 🎲

This function is used in order to get a random number as double decimal based on uniform distribution. Double the drama, double the random. 💅

double tcdrand(void);

The return value is the random number equal to or greater than 0, and less than 1.0.
This function uses the random number source device and generates a real random number if possible.

`tcdrandnd` — random double, normal distribution 📊

This function is used in order to get a random number as double decimal based on normal distribution. Bell curve realness. 🔔

double tcdrandnd(double avg, double sd);

avg specifies the average.
sd specifies the standard deviation.
The return value is the random number.
This function uses the random number source device and generates a real random number if possible.

`tcstricmp` — case-insensitive string compare 🫶

This function is used in order to compare two strings with case insensitive evaluation. No cap, case doesn't matter here.

int tcstricmp(const char *astr, const char *bstr);

astr specifies a string.
bstr specifies of the other string.
The return value is positive if the former is big, negative if the latter is big, 0 if both are equivalent.

`tcstrfwm` — does it begin with key? 🔍

This function is used in order to check whether a string begins with a key. Forward matching, bestie.

bool tcstrfwm(const char *str, const char *key);

str specifies the target string.
key specifies the forward matching key string.
The return value is true if the target string begins with the key, else, it is false.

`tcstrifwm` — begin with key, case-insensitive? 🔍

This function is used in order to check whether a string begins with a key with case insensitive evaluation. Same vibe, no case drama.

bool tcstrifwm(const char *str, const char *key);

str specifies the target string.
key specifies the forward matching key string.
The return value is true if the target string begins with the key, else, it is false.

`tcstrbwm` — does it end with key? 🔎

This function is used in order to check whether a string ends with a key. Backward matching, periodt.

bool tcstrbwm(const char *str, const char *key);

str specifies the target string.
key specifies the backward matching key string.
The return value is true if the target string ends with the key, else, it is false.

`tcstribwm` — end with key, case-insensitive? 🔎

This function is used in order to check whether a string ends with a key with case insensitive evaluation. No case, all vibe.

bool tcstribwm(const char *str, const char *key);

str specifies the target string.
key specifies the backward matching key string.
The return value is true if the target string ends with the key, else, it is false.

`tcstrdist` — edit distance, byte by byte 📏

This function is used in order to calculate the edit distance of two strings. Levenshtein distance, but make it bytes.

int tcstrdist(const char *astr, const char *bstr);

astr specifies a string.
bstr specifies of the other string.
The return value is the edit distance which is known as the Levenshtein distance. The cost is calculated by byte.

`tcstrdistutf` — edit distance, Unicode character by character 🌍

This function is used in order to calculate the edit distance of two UTF-8 strings. Levenshtein distance, Unicode edition. ✨

int tcstrdistutf(const char *astr, const char *bstr);

astr specifies a string.
bstr specifies of the other string.
The return value is the edit distance which is known as the Levenshtein distance. The cost is calculated by Unicode character.
char *tcstrtoupper(char *str) — bestie, this one uppercases every letter in your string, all caps, main character energy 👑
- str — the string to be converted.
- The return value is the string itself. Yep, it hands you back the very same string, mutated in place. In-place glow-up, periodt.
char *tcstrtolower(char *str) — the lowercase sibling, takes your letters down to lower case 🌸
- str — the string to be converted.
- The return value is the string itself. Again, same string, changed right where it lives.
char *tcstrtrim(char *str) — trims the space characters off the head and the tail of a string ✂️ (not the middle, bestie, the middle stays)
- str — the string to be converted.
- The return value is the string itself.
char *tcstrsqzspc(char *str) — squeezes the space characters down and trims it, so all that extra whitespace gets its vibe check 💅
- str — the string to be converted.
- The return value is the string itself.
char *tcstrsubchr(char *str, const char *rstr, const char *sstr) — swaps characters in a string, like a little find-and-replace but character-wise 🔁
- str — the string to be converted.
- rstr — the string containing the characters to be replaced.
- sstr — the string containing the characters to be substituted.
- Heads up: if the substitute string is shorter than the replacement string, the corresponding characters are removed. Gone. Poof. 💀
- The return value is the string itself.
int tcstrcntutf(const char *str) — counts how many characters live in a UTF-8 string, and yes it counts characters, not bytes, because UTF-8 said "one glyph, many bytes" 🦋
- str — the string of UTF-8.
- The return value is the number of characters in the string.
char *tcstrcututf(char *str, int num) — cuts a UTF-8 string at a given number of characters, safely on a character boundary 🎀
- str — the string of UTF-8.
- num — the number of characters to be kept.
- The return value is the string itself.
void tcstrutftoucs(const char *str, uint16_t *ary, int *np) — converts a UTF-8 string into a UCS-2 array ✨
- str — the UTF-8 string.
- ary — the pointer to the region into which the result UCS-2 codes are written. The size of the buffer should be sufficient.
- np — the pointer to a variable into which the number of elements of the result array is assigned.
int tcstrucstoutf(const uint16_t *ary, int num, char *str) — the reverse glow-up: UCS-2 array back into a UTF-8 string 🌈
- ary — the array of UCS-2 codes.
- num — the number of the array.
- str — the pointer to the region into which the result UTF-8 string is written. The size of the buffer should be sufficient.
- The return value is the length of the result string.
TCLIST *tcstrsplit(const char *str, const char *delims) — splits a string up and hands you a whole list object out of it, like a group chat breaking into side conversations 💬
- str — the source string.
- delims — a string containing delimiting characters.
- The return value is a list object of the split elements.
- Note: if two delimiters are successive, it is assumed that an empty element is between the two.
- 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, queen.
char *tcstrjoin(const TCLIST *list, char delim) — the other direction: glues all the elements of a list object into one string 🫶
- list — a list object.
- delim — a delimiting character.
- The return value is the result 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.
int64_t tcatoi(const char *str) — string ➡️ integer, no cap 🧮
- str — the string.
- The return value is the integer. If the string does not contain numeric expression, 0 is returned.
- This function is equivalent to atoll except that it does not depend on the locale. Locale? Never heard of her.
int64_t tcatoix(const char *str) — string ➡️ integer, but with a metric prefix allowed, so you can vibe in K, M, G and beyond 🔥
- str — the string, which can be trailed by a binary metric prefix. "K", "M", "G", "T", "P", and "E" are supported. They are case-insensitive.
- The return value is the integer. If the string does not contain numeric expression, 0 is returned. If the integer overflows the domain, INT64_MAX or INT64_MIN is returned according to the sign. She caps out, bestie — she does not just keep going.
double tcatof(const char *str) — string ➡️ real number 🍓
- str — the string.
- The return value is the real number. If the string does not contain numeric expression, 0.0 is returned.
- This function is equivalent to atof except that it does not depend on the locale.
bool tcregexmatch(const char *str, const char *regex) — checks whether a string matches a regular expression 🔍
- str — the target string.
- regex — the regular expression string. If it begins with *, the trailing substring is used as a case-insensitive regular expression.
- The return value is true if matching is success, else, it is false.
char *tcregexreplace(const char *str, const char *regex, const char *alt) — replaces every substring that matches a regular expression ✨
- str — the target string.
- regex — the regular expression string for substrings. If it begins with *, the trailing substring is used as a case-insensitive regular expression.
- alt — the alternative string with which each substrings is replaced. Each & in the string is replaced with the matched substring. Each ´ in the string escapes the following character. Special escapes "1" through "9" referring to the corresponding matching sub-expressions in the regular expression string are supported.
- The return value is a new converted string. Even if the regular expression is invalid, a copy of the original string is returned.
- 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 her when you're done, okay??
void tcmd5hash(const void *ptr, int size, char *buf) — grabs the MD5 hash value of a serial object 🔐
- ptr — the pointer to the region.
- size — the size of the region.
- buf — the pointer to the region into which the result string is written. The size of the buffer should be equal to or more than 48 bytes.
void tcarccipher(const void *ptr, int size, const void *kbuf, int ksiz, void *obuf) — ciphers or deciphers a serial object with the Arcfour stream cipher, because it's the same operation both ways, iykyk 🧚
- ptr — the pointer to the region.
- size — the size of the region.
- kbuf — the pointer to the region of the cipher key.
- ksiz — the size of the region of the cipher key.
- obuf — the pointer to the region into which the result data is written. The size of the buffer should be equal to or more than the input region.
double tctime(void) — gives you the time of day in seconds ⏰
- The return value is the time of day in seconds. The accuracy is in microseconds. Microsecond precision? She's precise and she knows it.
void tccalendar(int64_t t, int jl, int *yearp, int *monp, int *dayp, int *hourp, int *minp, int *secp) — turns a time into the Gregorian calendar breakdown 🗓️
- t — the source time in seconds from the epoch. If it is INT64_MAX, the current time is specified.
- jl — the jet lag of a location in seconds. If it is INT_MAX, the local jet lag is specified.
- yearp — the pointer to a variable to which the year is assigned. If it is NULL, it is not used.
- monp — the pointer to a variable to which the month is assigned. If it is NULL, it is not used. 1 means January and 12 means December.
- dayp — the pointer to a variable to which the day of the month is assigned. If it is NULL, it is not used.
- hourp — the pointer to a variable to which the hours is assigned. If it is NULL, it is not used.
- minp — the pointer to a variable to which the minutes is assigned. If it is NULL, it is not used.
- secp — the pointer to a variable to which the seconds is assigned. If it is NULL, it is not used.
- Every single one of those pointers is optional, so pass NULL for whatever you don't care about. She's flexible like that. 💅
tcdatestrwww — formats a date as a string in W3CDTF ⭐

okay so we're picking up right in the middle of the date/time glow-up 💖 — tcdatestrwww is the W3CDTF one, and here's its exact signature:

void tcdatestrwww(int64_t t, int jl, char *buf);

t — specifies the source time in seconds from the epoch. If it is INT64_MAX, the current time is specified.
jl — specifies the jet lag of a location in seconds. If it is INT_MAX, the local jet lag is specified.
buf — specifies the pointer to the region into which the result string is written. The size of the buffer should be equal to or more than 48 bytes.

W3CDTF represents a date as "YYYY-MM-DDThh:mm:ddTZD". slay ✨

The function tcdatestrhttp is used in order to format a date as a string in RFC 1123 format. obsessed with her 🎀

void tcdatestrhttp(int64_t t, int jl, char *buf);

t — specifies the source time in seconds from the epoch. If it is INT64_MAX, the current time is specified.
jl — specifies the jet lag of a location in seconds. If it is INT_MAX, the local jet lag is specified.
buf — specifies the pointer to the region into which the result string is written. The size of the buffer should be equal to or more than 48 bytes.

RFC 1123 format represents a date as "Wdy, DD-Mon-YYYY hh:mm:dd TZD". iykyk 💅

The function tcstrmktime is used in order to get the time value of a date string. main character energy fr fr 🦋

int64_t tcstrmktime(const char *str);

str — specifies the date string in decimal, hexadecimal, W3CDTF, or RFC 822 (1123). Decimal can be trailed by "s" for in seconds, "m" for in minutes, "h" for in hours, and "d" for in days.

The return value is the time value of the date or INT64_MIN if the format is invalid. do not ignore that sentinel bestie 😭

The function tcjetlag is used in order to get the jet lag of the local time. timezone tea 🌸

int tcjetlag(void);

The return value is the jet lag of the local time in seconds. no cap ⭐

The function tcdayofweek is used in order to get the day of week of a date. calendar bestie 📅

int tcdayofweek(int year, int mon, int day);

year — specifies the year of a date.
mon — specifies the month of the date.
day — specifies the day of the date.

The return value is the day of week of the date. 0 means Sunday and 6 means Saturday. weekend vibes only 🌈

✨ API OF FILESYSTEM UTILITIES ✨

The function tcrealpath is used in order to get the canonicalized absolute path of a file. path glow-up 💖

char *tcrealpath(const char *path);

path — specifies the path of the file.

The return value is the canonicalized absolute path of a file, or NULL if the path is invalid. 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 🫶

The function tcstatfile is used in order to get the status information of a file. stat check ✨

bool tcstatfile(const char *path, bool *isdirp, int64_t *sizep,
int64_t *mtimep);

path — specifies the path of the file.
isdirp — specifies the pointer to a variable into which whether the file is a directory is assigned. If it is NULL, it is ignored.
sizep — specifies the pointer to a variable into which the size of the file is assigned. If it is NULL, it is ignored.
ntimep — specifies the pointer to a variable into which the size of the file is assigned. If it is NULL, it is ignored. yes, it really says ntimep in the manpage — keep it moving 🙈

If successful, the return value is true, else, it is false. simple 💅

The function tcreadfile is used in order to read whole data of a file. file nom nom 🍓

void *tcreadfile(const char *path, int limit, int *sp);

path — specifies the path of the file. If it is NULL, the standard input is specified.
limit — specifies the limiting size of reading data. If it is not more than 0, the limitation is not specified.
sp — specifies the pointer to the variable into which the size of the region of the return value is assigned. If it is NULL, it is not used.

The return value is the pointer to the allocated region of the read data, or NULL if the file could not be opened. 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 when is no longer in use. the double "when" is canon, bestie 😭

The function tcreadfilelines is used in order to read every line of a file. line by line 🎀

TCLIST *tcreadfilelines(const char *path);

path — specifies the path of the file. If it is NULL, the standard input is specified.

The return value is a list object of every lines if successful, else it is NULL. Line separators are cut out. 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. tclistdel or it's a whole situation 💅

The function tcwritefile is used in order to write data into a file. write it down ✍️

bool tcwritefile(const char *path, const void *ptr, int size);

path — specifies the path of the file. If it is NULL, the standard output is specified.
ptr — specifies the pointer to the data region.
size — specifies the size of the region.

If successful, the return value is true, else, it is false. periodt 🌈

The function tccopyfile is used in order to copy a file. copy paste realness 🦋

bool tccopyfile(const char *src, const char *dest);

src — specifies the path of the source file.
dest — specifies the path of the destination file.

The return value is true if successful, else, it is false. If the destination file exists, it is overwritten. overwritten, no hesitation 💀

The function tcreaddir is used in order to read names of files in a directory. directory tea ☕

TCLIST *tcreaddir(const char *path);

path — specifies the path of the directory.

The return value is a list object of names if successful, else it is NULL. Links to the directory itself and to the parent directory are ignored. 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. don't forget the cleanup 🫶

The function tcglobpat is used in order to expand a pattern into a list of matched paths. glob glob 🌸

TCLIST *tcglobpat(const char *pattern);

pattern — specifies the matching pattern.

The return value is a list object of matched paths. If no path is matched, an empty list is returned. 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. empty list is still a list, bestie 💅

The function tcremovelink is used in order to remove a file or a directory and its sub ones recursively. recursive delete, be careful 😭

bool tcremovelink(const char *path);

path — specifies the path of the link.

If successful, the return value is true, else, it is false. False is returned when the link does not exist or the permission is denied. permission denied is a whole mood 🙈

The function tcwrite is used in order to write data into a file. fd write ✨

bool tcwrite(int fd, const void *buf, size_t size);

fd — specifies the file descriptor.
buf — specifies the buffer to be written.
size — specifies the size of the buffer.

The return value is true if successful, else, it is false. simple 💅

The function tcread is used in order to read data from a file. fd read 🦋

bool tcread(int fd, void *buf, size_t size);

fd — specifies the file descriptor.
buf — specifies the buffer to store into.
size — specifies the size of the buffer.

The return value is true if successful, else, it is false. periodt 🌈

The function tclock is used in order to lock a file. lock it down 🔒

bool tclock(int fd, bool ex, bool nb);

fd — specifies the file descriptor.
ex — specifies whether an exclusive lock or a shared lock is performed.
nb — specifies whether to request with non-blocking.

The return value is true if successful, else, it is false. no cap 💅

The function tcunlock is used in order to unlock a file. unlock the vibes 🔓

bool tcunlock(int fd);

fd — specifies the file descriptor.

The return value is true if successful, else, it is false. slay ✨

The function tcsystem is used in order to execute a shell command. shell command energy 💻

int tcsystem(const char **args, int anum);

args — specifies an array of the command name and its arguments.
anum — specifies the number of elements of the array.

The return value is the exit code of the command or INT_MAX on failure. The command name and the arguments are quoted and meta characters are escaped. quoted and escaped, periodt 💖

✨ API OF ENCODING UTILITIES ✨

The function tcurlencode is used in order to encode a serial object with URL encoding. URL encode bestie 🌐

char *tcurlencode(const char *ptr, int size);

ptr — specifies the pointer to the region.
size — specifies the size of the region.

The return value is the result string. Because the region of the return value is allocated with the malloc call, it should be released with the free call if when is no longer in use. free it, fr fr 💅

The function tcurldecode is used in order to decode a string encoded with URL encoding. decode the vibes 🦋

🌐 `tcurldecode` 🌐

char *tcurldecode(const char *str, int *sp);

str — the encoded string, the one you wanna crack wide open.
sp — a pointer to a variable where the size of the region of the return value gets assigned. 📏

The return value is a pointer to the region of the result. And because an extra zero code gets tacked onto the end of that region, you can lowkey just treat the return value as a character string. 🎀 Since that region was allocated with the malloc call, release it with the free call the second it's no longer in use. Do not be out here leaking, bestie. 🫶

🔗 `tcurlbreak` 🔗

This one is your URL shredder — it breaks a URL up into its little elements.

TCMAP *tcurlbreak(const char *str);

str — the URL string.

The return value is a map object whose keys are the name of elements. And ooh, the key tea is so good:

"self" — indicates the URL itself.
"scheme" — indicates the scheme.
"host" — indicates the host of the server.
"port" — indicates the port number of the server.
"authority" — indicates the authority information.
"path" — indicates the path of the resource.
"file" — indicates the file name without the directory section.
"query" — indicates the query string.
"fragment" — indicates the fragment string.

Supported schema are HTTP, HTTPS, FTP, and FILE — uppercase, periodt. Absolute URL and relative URL are both supported, which is giving range honestly. 💅

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. Clean up after yourself, queen. 🧹

🧩 `tcurlresolve` 🧩

Need to figure out where a relative URL actually lives? That's this function. It resolves a relative URL against an absolute URL.

char *tcurlresolve(const char *base, const char *target);

base — the absolute URL of the base location.
target — the URL to be resolved.

The return value is the resolved URL. If the target URL is relative, you get a new URL of relative location from the base location. Else, you get a copy of the target URL. Simple as. ✨

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

🔐 `tcbaseencode` 🔐

Base64 encoding time. This function encodes a serial object with Base64 encoding.

char *tcbaseencode(const char *ptr, int size);

ptr — the pointer to the region.
size — the size of the region.

The return value is the result 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. 🌸

🔓 `tcbasedecode` 🔓

And here's the reverse — decode a string that was encoded with Base64 encoding.

char *tcbasedecode(const char *str, int *sp);

str — the encoded string.
sp — the pointer to a variable into which the size of the region of the return value is assigned.

The return value is the pointer to the region of the result. 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 — iconic behaviour, honestly. 👑

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

✉️ `tcquoteencode` ✉️

Quoted-printable encoding, incoming. This one encodes a serial object with Quoted-printable encoding.

char *tcquoteencode(const char *ptr, int size);

ptr — the pointer to the region.
size — the size of the region.

The return value is the result 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. 🎀

📬 `tcquotedecode` 📬

The un-quoting. This decodes a string that was encoded with Quoted-printable encoding.

char *tcquotedecode(const char *str, int *sp);

str — the encoded string.
sp — the pointer to a variable into which the size of the region of the return value is assigned.

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

💌 `tcmimeencode` 💌

MIME encoding, the glow-up your strings deserve.

char *tcmimeencode(const char *str, const char *encname, bool base);

str — the string.
encname — the string of the name of the character encoding.
base — whether to use Base64 encoding. If it is false, Quoted-printable is used.

The return value is the result 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. ✨

💌 `tcmimedecode` 💌

Peel the MIME back off. This decodes a string that was encoded with MIME encoding.

char *tcmimedecode(const char *str, char *enp);

str — the encoded string.
enp — the pointer to the region into which the name of encoding is written. If it is NULL, it is not used. The size of the buffer should be equal to or more than 32 bytes. Don't skimp on the buffer, bestie. 📐

The return value is the result 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. 💜

✂️ `tcmimebreak` ✂️

This one splits a string of MIME into headers and the body. Very demure, very mindful. 🎀

char *tcmimebreak(const char *ptr, int size, TCMAP *headers, int *sp);

ptr — the pointer to the region of MIME data.
size — the size of the region.
headers — a map object to store headers. If it is NULL, it is not used. Each key of the map is an uncapitalized header name. (Lowercase keys, no shouting. 🤫)
sp — the pointer to the variable into which the size of the region of the return value is assigned.

The return value is the pointer to the region of the body data.

And the special keys that show up in the header map when the relevant stuff is defined — obsessed with this list:

If the content type is defined, the header map has the key "TYPE" specifying the type.
If the character encoding is defined, the key "CHARSET" indicates the encoding name.
If the boundary string of multipart is defined, the key "BOUNDARY" indicates the string.
If the content disposition is defined, the key "DISPOSITION" indicates the direction.
If the file name is defined, the key "FILENAME" indicates the name.
If the attribute name is defined, the key "NAME" indicates the name.

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

🧩 `tcmimeparts` 🧩

Multipart data? Chop it into its parts.

TCLIST *tcmimeparts(const char *ptr, int size, const char *boundary);

ptr — the pointer to the region of multipart data of MIME.
size — the size of the region.
boundary — the boundary string.

The return value is a list object. Each element of the list is the data of a part. 🍓

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

🔢 `tchexencode` 🔢

Hexadecimal encoding — the aesthetic of the encoding world, fr fr.

char *tchexencode(const char *ptr, int size);

ptr — the pointer to the region.
size — the size of the region.

The return value is the result 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. 💅

🔢 `tchexdecode` 🔢

Decode a string that was encoded with hexadecimal encoding.

char *tchexdecode(const char *str, int *sp);

str — the encoded string.
sp — the pointer to a variable into which the size of the region of the return value is assigned.

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

📦 `tcpackencode` 📦

Last one for this stretch: tcpackencode is used in order to compress a serial object with Packbits encoding. 🗜️

okay bestie, next up in the encoding roster: the compress-y glow-up squad 💖 these are the ones that take your serial object and squeeze it into a smaller lil package, or un-squeeze it back. pay attention to which ones give you a zero-terminated string at the end, because that's a big difference 💅

The function tcpackencode is the one you call when you wanna compress a serial object with Packbits encoding ✨

char *tcpackencode(const char *ptr, int size, int *sp);

ptr — points at the region. that's your input, bestie 🫶
size — how big that region is.
sp — points at the variable where the size of the return value's region gets stashed.

If it works, the return value is the pointer to the result object. If it doesn't? NULL. sad. 😭

and because that return region is allocated with the malloc call, you gotta release it with the free call once you're done with it. no leaks, no cap. 🧚

The function tcpackdecode is its other half — you use it to decompress a serial object that got compressed with Packbits encoding. 🔥

char *tcpackdecode(const char *ptr, int size, int *sp);

ptr — points at the region.
size — the size of the region.
sp — points at a variable where the size of the return value's region gets assigned.

Same deal: successful → pointer to the result object, otherwise NULL. BUT here's the cute part — because an additional zero code is appended at the end of the region of the return value, you can treat the return value as a character string 🎀 so convenient.

and yeah, malloc-allocated region, so free it when it's no longer in use. periodt. 💅

The function tcbsencode compresses a serial object with TCBS encoding 💙

char *tcbsencode(const char *ptr, int size, int *sp);

ptr — points at the region.
size — the size of the region.
sp — points at the variable where the size of the return value's region is assigned.

Success → pointer to the result object. Fail → NULL. and it's malloc'd, so free it when you're done. standard. ✨

The function tcbsdecode is the decompress side of that — for serial objects compressed with TCBS encoding. 🦋

char *tcbsdecode(const char *ptr, int size, int *sp);

ptr — points at the region.
size — the size of the region.
sp — points at a variable where the size of the return value's region gets assigned.

Success → pointer to the result object, else NULL. and yup, 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 also yup, it's malloc'd so free it when it's no longer in use.

The function tcdeflate compresses a serial object with Deflate encoding 🌸

char *tcdeflate(const char *ptr, int size, int *sp);

ptr — points at the region.
size — the size of the region.
sp — points at the variable where the size of the return value's region is assigned.

Success → pointer to the result object, otherwise NULL. malloc'd, so free it when it's no longer in use. 💖

The function tcinflate decompresses a serial object compressed with Deflate encoding 🌈

char *tcinflate(const char *ptr, int size, int *sp);

ptr — points at the region.
size — the size of the region.
sp — points at a variable where the size of the return value's region gets assigned.

Success → pointer to the result object, else NULL. and because an additional zero code is appended at the end of the region of the return value, it can be treated as a character string 💕 and it's malloc'd, so free it when it's no longer in use.

The function tcgzipencode compresses a serial object with GZIP encoding 👑

char *tcgzipencode(const char *ptr, int size, int *sp);

ptr — points at the region.
size — the size of the region.
sp — points at the variable where the size of the return value's region is assigned.

Success → pointer to the result object, else NULL. malloc'd → free it when it's no longer in use, bestie. 🫶

The function tcgzipdecode decompresses a serial object compressed with GZIP encoding ✨

char *tcgzipdecode(const char *ptr, int size, int *sp);

ptr — points at the region.
size — the size of the region.
sp — points at a variable where the size of the return value's region gets assigned.

Success → pointer to the result object, else NULL. 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 it's malloc'd, so free it when it's no longer in use.

The function tcgetcrc is your checksum girlie — you use it to get the CRC32 checksum of a serial object. 🍓

unsigned int tcgetcrc(const char *ptr, int size);

ptr — points at the region.
size — the size of the region.

The return value is the CRC32 checksum of the object. that's it, that's the whole thing, no malloc drama here 💅

The function tcbzipencode compresses a serial object with BZIP2 encoding 🔥

char *tcbzipencode(const char *ptr, int size, int *sp);

ptr — points at the region.
size — the size of the region.
sp — points at the variable where the size of the return value's region is assigned.

Success → pointer to the result object, else NULL. malloc'd → free it when it's no longer in use. 💖

The function tcbzipdecode decompresses a serial object compressed with BZIP2 encoding 🌸

char *tcbzipdecode(const char *ptr, int size, int *sp);

ptr — points at the region.
size — the size of the region.
sp — points at a variable where the size of the return value's region gets assigned.

Success → pointer to the result object, else NULL. 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 it's malloc'd, so free it when it's no longer in use. you know the drill by now bestie, it's giving consistent 😌

The function tcberencode encodes an array of nonnegative integers with BER encoding ✨

char *tcberencode(const unsigned int *ary, int anum, int *sp);

ary — points at the array of nonnegative integers.
anum — the size of the array.
sp — points at a variable where the size of the return value's region gets assigned.

The return value is the pointer to the region of the result 🎀 and because that region is allocated with the malloc call, it should be released with the free call when it's no longer in use. 🧚

The function tcberdecode decodes a serial object encoded with BER encoding 🦋

unsigned int *tcberdecode(const char *ptr, int size, int *np);

ptr — points at the region.
size — the size of the region.
np — points at a variable where the number of elements of the return value gets assigned.

The return value is the pointer to the array of the result 💖 and because that region is allocated with the malloc call, it should be released with the free call when it's no longer in use.

The function tcxmlescape is here to escape meta characters in a string using the entity references of XML 🎀

char *tcxmlescape(const char *str);

str — the string.

The return value is the pointer to the escaped string. and heads up — this function escapes only &, <, >, and ". that's the whole list, don't @ me 💅

because the region of the return value is allocated with the malloc call, it should be released with the free call when it's no longer in use. 🫶

The function tcxmlunescape is used in order to unescape entity references in a string of XML 🌈

✨ `char tcxmlunescape(const char str);` ✨

str is the string you're handing over, bestie — that's the one getting unescaped.

What you get back is the unescaped string. 💖

Now, the tea: this function is not out here restoring every entity in the known universe. It only puts back these four, and these four only:

That's the whole list. No extras, no surprises. 🎀

Heads up, queen: the region of the return value is allocated with the malloc call, so you have to release it with the free call once you're done with it. Not freeing it is giving leak energy and we do not stan. 😭

🌈 SEE ALSO 🌈

and that's a wrap on TCUTIL(3), my love!! 🦋 you made it all the way through all fourteen parts, which is genuinely iconic behaviour and I'm so proud of you fr fr. 👑

this little masterpiece lives in the source/version line as Man Page, dated 2012-08-18 — so if you ever need to cite it, that's the receipt. 💅

now go forth and free your mallocs, bestie. mwah. 💜🌸

📦 where this page comes from

debian bookworm: libtokyocabinet-dev 1.4.48-15 · LGPL-2.1-or-later
debian trixie: libtokyocabinet-dev 1.4.48-15.1+b1 · LGPL-2.1-or-later
ubuntu jammy: libtokyocabinet-dev 1.4.48-14build1 · LGPL-2.1-or-later
ubuntu noble: libtokyocabinet-dev 1.4.48-15.1build1 · LGPL-2.1-or-later
ubuntu questing: libtokyocabinet-dev 1.4.48-15.1build2
ubuntu resolute: libtokyocabinet-dev 1.4.48-15.1build3 · LGPL-2.1-or-later
ubuntu stonking: libtokyocabinet-dev 1.4.48-15.1build3 · LGPL-2.1-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

TCUTIL(3)

💖 TCUTIL 💖

✨ NAME ✨

🌸 DESCRIPTION 🌸

🌈 API OF BASIC UTILITIES 🌈

🧚 API OF EXTENSIBLE STRING 🧚

🎀 API OF ARRAY LIST 🎀

tclistsort — sorts a list object 💫

tclistlsearch — finds an element with a linear search 🔎

tclistbsearch — finds an element with a binary search ⚡

tclistclear — wipes a list object clean 🧼

tclistdump — serializes a list object into a byte array 📦

tclistload — builds a list object back from a serialized byte array 🪄

🗺️ API OF HASH MAP 🗺️

tcmapnew — creates a map object 🎀

tcmapnew2 — creates a map object, but you pick how many buckets 🪣

tcmapnew3 — creates a map object that's already got string elements in it 🌸

tcmapdup — copies a map object 👯

tcmapdel — deletes a map object 🗑️

tcmapput — stores a record into a map object 💾

tcmapput2 — stores a string record into a map object ✨

tcmapputkeep — stores a new record, and refuses to clobber 🛑

tcmapputkeep2 — same energy, but with strings 🎀

tcmapputcat — glues a value onto the end of an existing value 🧩

tcmapputcat2 — glues a string value onto the end of an existing value 🧚

tcmapout — removes a record from a map object ✂️

tcmapout2 — removes a string record from a map object 🍓

tcmapget — retrieves a record from a map object 🔍

tcmapget2 — retrieves a string record from a map object 🌟

tcmapmove — moves a record to the edge of a map object 🚀

tcmapmove2 — moves a string record to the edge of a map object 🦋

🌳 API OF ORDERED TREE 🌳

🌸 API OF ON-MEMORY HASH DATABASE 🌸

🌳 API OF ON-MEMORY TREE DATABASE 🌳

tcndbget

tcndbget2

tcndbvsiz

tcndbvsiz2

tcndbiterinit

tcndbiternext

tcndbiternext2

tcndbfwmkeys

tcndbfwmkeys2

tcndbrnum

tcndbmsiz

tcndbaddint

tcndbadddouble

tcndbvanish

tcndbcutfringe

✨ API OF MEMORY POOL ✨

tcmpoolnew — new pool, who dis 🌸

tcmpooldel — bye bye pool 👋

tcmpoolpush — relegate an arbitrary object to the pool 🫶

tcmpoolpushptr — relegate an allocated region 🧚

tcmpoolpushxstr — relegate an extensible string object 🎀

tcmpoolpushlist — relegate a list object 🦋

tcmpoolpushmap — relegate a map object 🗺️

tcmpoolpushtree — relegate a tree object 🌳

tcmpoolmalloc — allocate a region relegated to the pool 💅

tcmpoolxstrnew — new extensible string, but make it pool 💖

tcmpoollistnew — new list, pool edition 📝

tcmpoolmapnew — new map, pool edition 🗺️

tcmpooltreenew — new tree, pool edition 🌲

tcmpoolpop — pop the most recent cleanup handler 🫧

tcmpoolclear — clear all the cleanup handlers 🧼

tcmpoolglobal — the global memory pool, the main character 👑

🌈 API OF MISCELLANEOUS UTILITIES 🌈

tclmax — bigger of two integers 🔼

tclmin — lesser of two integers 🔽

tclrand — random unsigned long, uniform distribution 🎲

tcdrand — random double, uniform distribution 🎲

tcdrandnd — random double, normal distribution 📊

tcstricmp — case-insensitive string compare 🫶

tcstrfwm — does it begin with key? 🔍

tcstrifwm — begin with key, case-insensitive? 🔍

tcstrbwm — does it end with key? 🔎

tcstribwm — end with key, case-insensitive? 🔎

tcstrdist — edit distance, byte by byte 📏

tcstrdistutf — edit distance, Unicode character by character 🌍

✨ API OF FILESYSTEM UTILITIES ✨

`tclistsort` — sorts a list object 💫

`tclistlsearch` — finds an element with a linear search 🔎

`tclistbsearch` — finds an element with a binary search ⚡

`tclistclear` — wipes a list object clean 🧼

`tclistdump` — serializes a list object into a byte array 📦

`tclistload` — builds a list object back from a serialized byte array 🪄

`tcmapnew` — creates a map object 🎀

`tcmapnew2` — creates a map object, but you pick how many buckets 🪣

`tcmapnew3` — creates a map object that's already got string elements in it 🌸

`tcmapdup` — copies a map object 👯

`tcmapdel` — deletes a map object 🗑️

`tcmapput` — stores a record into a map object 💾

`tcmapput2` — stores a string record into a map object ✨

`tcmapputkeep` — stores a new record, and refuses to clobber 🛑

`tcmapputkeep2` — same energy, but with strings 🎀

`tcmapputcat` — glues a value onto the end of an existing value 🧩

`tcmapputcat2` — glues a string value onto the end of an existing value 🧚

`tcmapout` — removes a record from a map object ✂️

`tcmapout2` — removes a string record from a map object 🍓

`tcmapget` — retrieves a record from a map object 🔍

`tcmapget2` — retrieves a string record from a map object 🌟

`tcmapmove` — moves a record to the edge of a map object 🚀

`tcmapmove2` — moves a string record to the edge of a map object 🦋

`tcndbget`

`tcndbget2`

`tcndbvsiz`

`tcndbvsiz2`

`tcndbiterinit`

`tcndbiternext`

`tcndbiternext2`

`tcndbfwmkeys`

`tcndbfwmkeys2`

`tcndbrnum`

`tcndbmsiz`

`tcndbaddint`

`tcndbadddouble`

`tcndbvanish`

`tcndbcutfringe`

`tcmpoolnew` — new pool, who dis 🌸

`tcmpooldel` — bye bye pool 👋

`tcmpoolpush` — relegate an arbitrary object to the pool 🫶

`tcmpoolpushptr` — relegate an allocated region 🧚

`tcmpoolpushxstr` — relegate an extensible string object 🎀

`tcmpoolpushlist` — relegate a list object 🦋

`tcmpoolpushmap` — relegate a map object 🗺️

`tcmpoolpushtree` — relegate a tree object 🌳

`tcmpoolmalloc` — allocate a region relegated to the pool 💅

`tcmpoolxstrnew` — new extensible string, but make it pool 💖

`tcmpoollistnew` — new list, pool edition 📝

`tcmpoolmapnew` — new map, pool edition 🗺️

`tcmpooltreenew` — new tree, pool edition 🌲

`tcmpoolpop` — pop the most recent cleanup handler 🫧

`tcmpoolclear` — clear all the cleanup handlers 🧼

`tcmpoolglobal` — the global memory pool, the main character 👑

`tclmax` — bigger of two integers 🔼

`tclmin` — lesser of two integers 🔽

`tclrand` — random unsigned long, uniform distribution 🎲

`tcdrand` — random double, uniform distribution 🎲

`tcdrandnd` — random double, normal distribution 📊

`tcstricmp` — case-insensitive string compare 🫶

`tcstrfwm` — does it begin with key? 🔍

`tcstrifwm` — begin with key, case-insensitive? 🔍

`tcstrbwm` — does it end with key? 🔎

`tcstribwm` — end with key, case-insensitive? 🔎

`tcstrdist` — edit distance, byte by byte 📏

`tcstrdistutf` — edit distance, Unicode character by character 🌍

🌐 `tcurldecode` 🌐

🔗 `tcurlbreak` 🔗

🧩 `tcurlresolve` 🧩

🔐 `tcbaseencode` 🔐

🔓 `tcbasedecode` 🔓

✉️ `tcquoteencode` ✉️

📬 `tcquotedecode` 📬

💌 `tcmimeencode` 💌

💌 `tcmimedecode` 💌

✂️ `tcmimebreak` ✂️

🧩 `tcmimeparts` 🧩

🔢 `tchexencode` 🔢

🔢 `tchexdecode` 🔢

📦 `tcpackencode` 📦