Tcl_GetKeyedListKeys(3tcl)

💖 Tcl_GetKeyedListKeys — the keyed list glow-up 💖

okay bestie, sit down, hydrate, because we're talking about the keyed list management routines from the 3tcl manual. yes this page is literally named Tcl_GetKeyedListKeys but it's actually a whole squad of functions. we love a group effort. 🫶

---

✨ NAME ✨

TclX_NewKeyedListObj, TclX_KeyedListGet, TclX_KeyedListSet, TclX_KeyedListDelete, TclX_KeyedListGetKeys — the keyed list management routines, aka the girlies who handle your keyed lists for you. 💅

---

🌸 SYNOPSIS 🌸

#include <tclExtend.h>

Tcl_Obj *
TclX_NewKeyedListObj (void);

int
TclX_KeyedListGet (Tcl_Interp *interp,
                   Tcl_Obj    *keylPtr,
                   char       *key,
                   Tcl_Obj   **valuePtrPtr);

int
TclX_KeyedListSet (Tcl_Interp *interp,
                   Tcl_Obj    *keylPtr,
                   char       *key,
                   Tcl_Obj    *valuePtr);

int
TclX_KeyedListDelete (Tcl_Interp *interp,
                      Tcl_Obj    *keylPtr,
                      char       *key);

int
TclX_KeyedListGetKeys (Tcl_Interp *interp,
                       Tcl_Obj    *keylPtr,
                       char       *key,
                       Tcl_Obj   **listObjPtrPtr);

---

🦋 DESCRIPTION 🦋

so these routines do operations on keyed lists. that's the whole vibe. 💖

if you want the full lore on what a keyed list even is, go read the Extended Tcl man page. this page is just the operations, no origin story.

---

🎀 TclX_NewKeyedListObj 🎀

create and initialize a new keyed list object. fresh out the box, brand new, no notes. ✨

Returns:

• a pointer to the object. that's it, that's the whole return. 👑

---

💜 TclX_KeyedListGet 💜

retrieve a key value from a keyed list. the "give me that one thing" function.

Parameters:

• interp — error message will be return in result if there is an error.
• keylPtr — keyed list object to get key from.
• key — the name of the key to extract. will recusively process sub-keys separated by '.'.
• valueObjPtrPtr — if the key is found, a pointer to the key object is returned here. NULL is returned if the key is not present.

Returns:

• TCL_OK — if the key value was returned. slay. ✅
• TCL_BREAK — if the key was not found. 💀
• TCL_ERROR — if an error occurred. 😭

quick heads up bestie: yes, the original says "recusively." we're keeping the facts exactly as written because that's the rule. also interp says "will be return in result" — same deal, copying the truth, not fixing the grammar. 💅

---

🔥 TclX_KeyedListSet 🔥

set a key value in keyed list object. this is the "put that thing down right here" function.

Parameters:

• interp — error message will be return in result object.
• keylPtr — keyed list object to update.
• key — the name of the key to extract. will recusively process sub-key separated by '.'.
• valueObjPtr — the value to set for the key.

Returns:

• TCL_OK or TCL_ERROR. no in between, no gray area, it's giving binary. ✨

---

🌈 TclX_KeyedListDelete 🌈

delete a key value from keyed list. the "and we are never speaking again" function. 🙈

Parameters:

• interp — error message will be return in result if there is an error.
• keylPtr — keyed list object to update.
• key — the name of the key to extract. will recusively process sub-key separated by '.'.

Returns:

• TCL_OK — if the key was deleted. gone, deleted, blocked. ✅
• TCL_BREAK — if the key was not found. it was never there bestie. 💀
• TCL_ERROR — if an error occurred. 😭

---

🧚 TclX_KeyedListGetKeys 🧚

retrieve a list of keyed list keys. basically "who's in the group chat" but for your keyed list. 👑

Parameters:

• interp — error message will be return in result if there is an error.
• keylPtr — keyed list object to get key from.
• key — the name of the key to get the sub keys for. NULL or empty to retrieve all top level keys.
• listObjPtrPtr — list object is returned here with key as values.

Returns:

• TCL_OK — if the zero or more key where returned. ⭐
• TCL_BREAK — if the key was not found. 💀
• TCL_ERROR — if an error occurred. 😭

---

🫶 the sign-off 🫶

and that's the page, bestie. this whole thing comes to you from the Tcl manual, filed under Tcl_GetKeyedListKeys(3tcl). you're welcome, go forth and manage your keyed lists responsibly. no cap. 💖✨🎀🦋🌸💅