Tcl_BooleanObj(3tcl)

🦋 Tcl_BooleanObj 🦋

okay bestie, welcome to the Tcl Library Procedures page for Tcl_BooleanObj — yes it's a whole manual page whose whole personality is "put a yes/no into a Tcl_Obj and get it back out". No cap, that's the entire plot. 💅

---

🌸 NAME 🌸

Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj, Tcl_GetBoolFromObj — store/retrieve boolean value in a Tcl_Obj 🎀

---

✨ SYNOPSIS ✨

#include <tcl.h>

Tcl_Obj *
Tcl_NewBooleanObj(intValue)

Tcl_SetBooleanObj(objPtr, intValue)

int
Tcl_GetBooleanFromObj(interp, objPtr, boolPtr)

int
Tcl_GetBoolFromObj(interp, objPtr, flags. charPtr)

---

💖 ARGUMENTS 💖

• int intValue (in) — the integer value you wanna stash as a boolean value inside a Tcl_Obj.
• Tcl_Obj *objPtr (in/out) — points at the Tcl_Obj you're storing a boolean value into, or the one you're retrieving a boolean value from. She does both, she contains multitudes. 🫶
• Tcl_Interp *interp (in/out) — if a boolean value can't be retrieved, an error message gets left in the interpreter's result value — unless interp is NULL, in which case, nothing, silence, crickets.
• bool | int *boolPtr (out) — points to the place where Tcl_GetBooleanFromObj stores the boolean value (0 or 1) it obtained from objPtr.
• char *charPtr (out) — points to the place where Tcl_GetBoolFromObj stores the boolean value (0 or 1) it obtained from objPtr.
• int flags (in) — 0 or TCL_NULL_OK. If TCL_NULL_OK is used, then the empty string or NULL will result in Tcl_GetBoolFromObj return TCL_OK, the *charPtr filled with the value '\xFF';

---

🌈 DESCRIPTION 🌈

These procedures are literally the messenger service between you and Tcl when it comes to boolean values, and the messages travel as Tcl_Obj's. When you store a boolean value into a Tcl_Obj, any non-zero integer value in intValue is taken to be the boolean value 1, and the integer value 0 is taken to be the boolean value 0. That's the whole translation table, it's two entries, slay.

Tcl_NewBooleanObj creates a brand new Tcl_Obj, stores the boolean value intValue in it, and hands you back a pointer to the new Tcl_Obj. The new Tcl_Obj has reference count of zero — fresh out the box, zero commitments. ✨

Tcl_SetBooleanObj accepts objPtr, a pointer to an existing Tcl_Obj, and stores in the Tcl_Obj *objPtr the boolean value intValue. This is a write operation on *objPtr, so objPtr must be unshared. Attempts to write to a shared Tcl_Obj will panic. 💀 A successful write of intValue into *objPtr implies the freeing of any former value stored in *objPtr — out with the old, in with the new.

Tcl_GetBooleanFromObj attempts to retrieve a boolean value from the value stored in *objPtr. If objPtr holds a string value recognized by Tcl_GetBoolean, then the recognized boolean value is written at the address given by boolPtr. If objPtr holds any value recognized as a number by Tcl, then if that value is zero a 0 is written at the address given by boolPtr, and if that value is non-zero a 1 is written at the address given by boolPtr. In all cases where a value is written at the address given by boolPtr, Tcl_GetBooleanFromObj returns TCL_OK. If the value of objPtr does not meet any of the conditions above, then TCL_ERROR is returned and an error message is left in the interpreter's result unless interp is NULL. And plot twist: Tcl_GetBooleanFromObj may also make changes to the internal fields of *objPtr so that future calls to Tcl_GetBooleanFromObj on the same objPtr can be performed more efficiently. She's optimizing herself for next time, main character energy. 👑

Tcl_GetBoolFromObj functions almost the same as Tcl_GetBooleanFromObj, but it has an additional parameter flags, which can be used to specify whether the empty string or NULL is accepted as valid. Basically the same girl with one extra option. 🎀

⚠️ Note that the routines Tcl_GetBooleanFromObj and Tcl_GetBoolean are not functional equivalents. The set of values for which Tcl_GetBooleanFromObj will return TCL_OK is strictly larger than the set of values for which Tcl_GetBoolean will do the same. For example, the value “5” passed to Tcl_GetBooleanFromObj will lead to a TCL_OK return (and the boolean value 1), while the same value passed to Tcl_GetBoolean will lead to a TCL_ERROR return. Same value, two completely different reactions. It's giving sibling rivalry. 😭

---

🫶 REFERENCE COUNT MANAGEMENT 🫶

• Tcl_NewBooleanObj always returns a zero-reference object, much like Tcl_NewObj.
• Tcl_SetBooleanObj does not modify the reference count of its objPtr argument, but does require that the object be unshared.
• Tcl_GetBooleanFromObj does not modify the reference count of its objPtr argument; it only reads. Note however that this function may set the interpreter result; if that is the only place that is holding a reference to the object, it will be deleted. 😳

---

👀 SEE ALSO 👀

Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean

---

💜 KEYWORDS 💜

boolean, value

---

okay that's the whole page bestie, you're officially fluent in boolean Tcl_Obj behavior 💖 this one shipped with Tcl 8.5 and it's filed under Tcl_BooleanObj(3tcl) — go forth and store some booleans, you've got this 🎀✨