Tcl_GetKeyedListKeys(3tclx)

💖 NAME 💖

TclX_NewKeyedListObj, TclX_KeyedListGet, TclX_KeyedListSet, TclX_KeyedListDelete, TclX_KeyedListGetKeys — bestie, these are the keyed list management routines. That's the whole assignment. ✨

Oh and btw, this whole page lives in the 3tclx section of the manual, so you know exactly where you are. 🫶

---

📖 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 🦋

okay so real talk: these routines do operations on keyed lists. 💅 Wanna know what a keyed list even is? The Extended Tcl man page has the whole lore drop — go read that one, iykyk. 📚✨

🌟 TclX_NewKeyedListObj 🌟

Create and initialize a brand new keyed list object. It's giving fresh notebook, first page, no mistakes yet. 🎀

Returns:

• A pointer to the object. 🫶

---

🔑 TclX_KeyedListGet 🔑

Retrieve a key value from a keyed list. Slay, honestly. ✨

Parameters:

• interp — if there's an error, the error message will be returned in the result. 😭
• keylPtr — the keyed list object to get the key from.
• key — the name of the key to extract. It will recursively process sub-keys separated by . (that's a literal dot, bestie, don't come for me).
• valuePtrPtr — if the key is found, a pointer to the key object is returned here. NULL is returned if the key is not present. 🙈 (the page's own description calls this one valueObjPtrPtr — same parameter, just the manpage being quirky 💀)

Returns:

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

---

✨ TclX_KeyedListSet ✨

Set a key value in a keyed list object. Main character behavior, lowkey. 💅

Parameters:

• interp — the error message will be returned in the result object.
• keylPtr — the keyed list object to update.
• key — the name of the key to extract. It will recursively process sub-key separated by ..
• valuePtr — the value to set for the key. (the description spells this one valueObjPtr, same deal, we move 🌸)

Returns:

• TCL_OK or TCL_ERROR. That's it, no TCL_BREAK in the mix, periodt. 💖

---

🗑️ TclX_KeyedListDelete 🗑

Delete a key value from a keyed list. Not me removing things... 🙈

Parameters:

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

Returns:

• TCL_OK — if the key was deleted. 🎉
• TCL_BREAK — if the key was not found.
• TCL_ERROR — if an error occurred. 💀

---

🌈 TclX_KeyedListGetKeys 🌈

Retrieve a list of keyed list keys. So many keys, it's giving janitor energy. 🔑🔑🔑

Parameters:

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

Returns:

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

---

Friendly reminder bestie: TCL_BREAK shows up in TclX_KeyedListGet, TclX_KeyedListDelete and TclX_KeyedListGetKeys, but not in TclX_KeyedListSet — that one only ever gives you TCL_OK or TCL_ERROR. Don't go looking for a break that isn't there. 🫶

---

mwah 💋 that's the whole page, no notes. This one is served fresh from the Tcl manual, filed under Tcl_GetKeyedListKeys(3tclx) — go forth and manage your keyed lists, you absolute icon. 🧚💜