Tcl_GetKeyedListKeys(TCL)

💖 NAME 💖

okay bestie, meet the whole keyed-list management squad: TclX_NewKeyedListObj, TclX_KeyedListGet, TclX_KeyedListSet, TclX_KeyedListDelete, and TclX_KeyedListGetKeys. They're the keyed list management routines, and yes, they're all on the same friend group.

psst — this is the page for Tcl_GetKeyedListKeys(TCL), living in the Tcl manual. iykyk 🎀

---

✨ 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. If you need the whole lore drop on what a keyed list even is, go read the Extended Tcl man page — it's giving origin story. 💅

🦋 TclX_NewKeyedListObj

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

Returns:

• A pointer to the object. 👑

🎀 TclX_KeyedListGet

Retrieve a key value from a keyed list. literally the "bestie hand me that" of the group.

Parameters:

• interp — if there's an error, the error message gets returned in the result.
• keylPtr — the keyed list object we're getting the key from.
• key — the name of the key to extract. it will recursively process sub-keys separated by '.'. 🫶
• valueObjPtrPtr — if the key is found, a pointer to the key object gets returned here. NULL is returned if the key is not present. (not me checking for the NULL... 😭)

Returns:

• TCL_OK — if the key value was returned. slay.
• 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 energy, you're putting your mark on it.

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-keys separated by '.'.
• valueObjPtr — the value to set for the key.

Returns:

• TCL_OK or TCL_ERROR. that's the whole vibe check.

🌈 TclX_KeyedListDelete

Delete a key value from a keyed list. we're Marie Kondo-ing that key, it no longer sparks joy. 🗑️✨

Parameters:

• interp — if there's an error, the error message gets returned in the result.
• keylPtr — the keyed list object to update.
• key — the name of the key to extract. it will recursively process sub-keys 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. the "who's all here" headcount of the function family. 👑

Parameters:

• interp — if there's an error, the error message gets returned in the result.
• keylPtr — the keyed list object to get keys from.
• key — the name of the key to get the sub keys for. NULL or empty to retrieve all top level keys. 🫶
• 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.

---

fr fr, read those return values carefully — TCL_BREAK is not the same as TCL_ERROR, and mixing them up is lowkey a vibe killer. 😭

---

and that's the whole page, bestie! this icon came from the Tcl manual, filed under Tcl_GetKeyedListKeys(TCL). no cap, go write some keyed lists now. periodt 💅💖🎀