Tcl_BooleanObj(3)

💖 NAME 💖

ok so bestie, meet the girlies of the boolean Tcl_Obj world — Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj, and Tcl_GetBoolFromObj. their whole job? storing and retrieving a boolean value in a Tcl_Obj. that's it. that's the vibe. 🎀

this page lives in the Tcl Library Procedures section of the manual (section 3, iykyk).

---

✨ 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)

ok yes, that flags. charPtr is literally what the page says, don't come for me, I'm just the messenger 💀

---

🌸 ARGUMENTS 🌸

• int intValue (in) — the integer value that's getting stored as a boolean inside a Tcl_Obj.
• Tcl_Obj *objPtr (in/out) — points at the Tcl_Obj you're storing into, or the one you're retrieving from.
• Tcl_Interp *interp (in/out) — if a boolean value can't be retrieved, an error message gets parked in the interpreter's result value… unless interp is NULL, in which case, silence. 🙈
• bool | int *boolPtr (out) — points to the spot where Tcl_GetBooleanFromObj stores the boolean value (0 or 1) it pulled out of objPtr.
• char *charPtr (out) — points to the spot where Tcl_GetBoolFromObj stores the boolean value (0 or 1) it pulled out of objPtr.
• int flags (in) — 0 or TCL_NULL_OK. if you pass TCL_NULL_OK, then the empty string or NULL will make Tcl_GetBoolFromObj return TCL_OK, with *charPtr filled in with the value '\xFF'.

---

🦋 DESCRIPTION 🦋

these procedures are how boolean values get passed to and from Tcl as Tcl_Obj's. here's the tea: when you store a boolean into a Tcl_Obj, any non-zero integer in intValue counts as boolean 1, and the integer 0 counts as boolean 0. simple as that, no cap. ✨

Tcl_NewBooleanObj creates a brand new Tcl_Obj, stashes the boolean value intValue inside it, and hands you back a pointer to that new Tcl_Obj. the new Tcl_Obj has a reference count of zero.

Tcl_SetBooleanObj takes objPtr — a pointer to an existing Tcl_Obj — and stores the boolean value intValue into the Tcl_Obj *objPtr. this is a write operation on *objPtr, so objPtr must be unshared. attempting to write to a shared Tcl_Obj will panic. not cute. not slay. don't do it. 😭 a successful write of intValue into *objPtr means any former value stored in *objPtr gets freed — out with the old, in with the new 💅.

Tcl_GetBooleanFromObj tries to retrieve a boolean value from whatever's stored in *objPtr. here's how it goes down:

• if objPtr holds a string value that Tcl_GetBoolean recognizes, then the recognized boolean value gets written at the address given by boolPtr.
• if objPtr holds any value that Tcl recognizes as a number, then: if that value is zero, a 0 is written at the address given by boolPtr; if that value is non-zero, a 1 is written at the address given by boolPtr.
• in all cases where a value gets written at the address given by boolPtr, Tcl_GetBooleanFromObj returns TCL_OK.
• if the value of objPtr doesn't meet any of those conditions, then TCL_ERROR is returned and an error message gets left in the interpreter's result — unless interp is NULL.

also, Tcl_GetBooleanFromObj may make changes to the internal fields of *objPtr so that future calls to Tcl_GetBooleanFromObj on the same objPtr can run more efficiently. it's optimizing. let her cook. 👑

Tcl_GetBoolFromObj does almost exactly what Tcl_GetBooleanFromObj does, except it has that extra flags parameter, which lets you say whether the empty string or NULL is accepted as valid. glow-up behavior honestly. 🫶

⚠️ big important note bestie: Tcl_GetBooleanFromObj and Tcl_GetBoolean are not functional equivalents. the set of values where Tcl_GetBooleanFromObj returns TCL_OK is strictly larger than the set where Tcl_GetBoolean does the same. for example: the value “5” passed to Tcl_GetBooleanFromObj gives you a TCL_OK return (and the boolean value 1), while that same value passed to Tcl_GetBoolean gives you a TCL_ERROR return. same input, different energy. that's the whole point.

---

👑 REFERENCE COUNT MANAGEMENT 👑

keep track of the refs, bestie, it's giving responsible:

• Tcl_NewBooleanObj always returns a zero-reference object, a lot like Tcl_NewObj.
• Tcl_SetBooleanObj does not modify the reference count of its objPtr argument, but it does require that the object be unshared.
• Tcl_GetBooleanFromObj does not modify the reference count of its objPtr argument — it only reads. but heads up: this function may set the interpreter result, and if that's the only place holding a reference to the object, it will be deleted. 😭

---

🌈 SEE ALSO 🌈

Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean

---

⭐ KEYWORDS ⭐

boolean, value

---

ok that's the whole page, you ate it, periodt 💅✨ this was the Tcl manual, version 8.5, and you were reading Tcl_BooleanObj(3) — go forth and store those booleans responsibly, bestie 🦋🌸