libtar_list_new(3)

💖 libtar_list_new(3) 💖

okay bestie, gather round, because we're talking about the linked list routines from the libtar C library — this is a libtar_list_new(3) situation and it's genuinely iconic. it's giving data-structures-that-hold-your-hand. periodt. 🎀

✨ NAME ✨

libtar_list_new, libtar_list_free, libtar_list_next, libtar_list_prev, libtar_list_add, libtar_list_del, libtar_list_search, libtar_list_dup, libtar_list_merge, libtar_list_add_str — linked list routines 🦋

✨ SYNOPSIS ✨

#include <libtar.h>

libtar_list_t *libtar_list_new(int flags, int (*cmpfunc)());
void libtar_list_free(libtar_list_t *l, void (*freefunc)());
int libtar_list_add_str(libtar_list_t *l, char *str, char *delim);
int libtar_list_add(libtar_list_t *l, void *data);
void libtar_list_del(libtar_list_t *l, libtar_node_t **n);
int libtar_list_search(libtar_list_t *l, libtar_node_t **n, void *data,
int (*matchfunc)());
int libtar_list_next(libtar_list_t *l, libtar_node_t **n);
int libtar_list_prev(libtar_list_t *l, libtar_node_t **n);
libtar_list_t *libtar_list_dup(libtar_list_t *l);
libtar_list_t *libtar_list_merge(int (*cmpfunc)(), int flags,
libtar_list_t *list1, libtar_list_t *list2);

✨ DESCRIPTION ✨

so the libtar_list_new() function makes you a brand new list. main character moment fr fr. and the flags argument has to be one of these three values, no negotiating bestie:

• LIST_USERFUNC — the cmpfunc argument points at a user-supplied function, and that function is what decides the ordering of the list. you're the boss of the vibes. 💅
• LIST_STACK — use the list as a stack. new elements get added to the front of the list. first in, last out, no cap. 🥞
• LIST_QUEUE — use the list as a queue. new elements get added to the end of the list. polite. orderly. standing in line energy. 🚶♀️

the libtar_list_free() function deallocates all the memory associated with the list l. and if freefunc is not NULL, it gets called to free the memory associated with each node in the list. clean up after yourself, it's the respectful thing to do. 🧹✨

the libtar_list_add() function adds the element pointed to by data to the list l. where does the new element land? determined by the flags that were passed to libtar_list_new() back when the list was created. the list remembers. she always remembers. 🫶

the libtar_list_add_str() function tokenizes the string str using the delimiter characters in the string delim. then all those resulting tokens get added to list l using libtar_list_add(). it's a little chop-chop-then-insert situation. 🍓

the libtar_list_search() function searches for an element that matches data, using the matching function matchfunc. if matchfunc is NULL, a default matching function designed for ASCII strings gets used instead — she's got a fallback, she's prepared. searching begins from the node pointed to by n. 🔍

the libtar_list_del() function removes the entry pointed to by n from the list pointed to by l. bye babe! 💀

the libtar_list_dup() function creates a copy of the list l, and yes it uses dynamically allocated memory to do it. a twin. a clone. an understudy. 🌈

the libtar_list_merge() function creates a new list with flags and cmpfunc, exactly the same way libtar_list_new() does. then it adds all the elements from list1 and list2 using libtar_list_add(). two lists become one. soulmate behaviour. 💜

✨ RETURN VALUE ✨

• the libtar_list_new(), libtar_list_dup(), and libtar_list_merge() functions return a pointer to the new list structure, or NULL on error. 😭
• the libtar_list_next(), libtar_list_prev(), and libtar_list_search() functions return 1 when valid data is returned, or 0 otherwise. 👑
• the libtar_list_add() and libtar_list_add_str() functions return 0 on success, or -1 on error. 🔥

✨ SEE ALSO ✨

• libtar_hash_new(3) — go read that one next bestie, it's a whole other vibe 🌸

k that's the whole page, you ate it, you understood it, I'm obsessed. this lil manual page came from the University of Illinois, dated Jan 2000 — old money, timeless energy, still serving. mwah. 💅✨🦋