Tcl_ExprLongObj(3tcl)

💖 Tcl_ExprLongObj — the "evaluate an expression" besties 💖

ok so this is the Tcl Library Procedures page for Tcl_ExprLongObj and its three girlies, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, and Tcl_ExprObj. four functions, one job: evaluate an expression ✨

---

✨ NAME ✨

Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj — evaluate an expression 🧚

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

int
Tcl_ExprLongObj(interp, objPtr, longPtr)

int
Tcl_ExprDoubleObj(interp, objPtr, doublePtr)

int
Tcl_ExprBooleanObj(interp, objPtr, booleanPtr)

int
Tcl_ExprObj(interp, objPtr, resultPtrPtr)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter in whose context we evaluate objPtr. she's the whole vibe, she holds the variables and the nested commands and the drama (errors).
• Tcl_Obj *objPtr (in) — pointer to a value holding the expression we're about to evaluate. yes bestie, the expression lives inside a Tcl_Obj.
• long *longPtr (out) — pointer to the spot where the integer value of the expression goes.
• int *doublePtr (out) — pointer to the spot where the floating-point value of the expression goes. (yes, the manpage literally types it int * here, we don't question the ancestors 🙈)
• int *booleanPtr (out) — pointer to the spot where the 0/1 boolean value of the expression goes.
• Tcl_Obj **resultPtrPtr (out) — pointer to the spot where we stash a pointer to the value that is the result of the expression. pointer-to-a-pointer, iconic behavior, she contains multitudes 💅

---

💅 DESCRIPTION 💅

okay so all four of these procedures evaluate an expression, and they just hand the answer back in four different forms. the expression comes in through the objPtr argument, and it can take any of the forms that the expr command accepts. anything expr can do, these can do. no cap.

the interp argument is the interpreter used to evaluate the expression — she's the one with the variables, the nested Tcl commands, all of it — and she's also the one who returns error info when things go sideways.

for all of these procedures the return value is a standard Tcl result:

• TCL_OK means the expression was successfully evaluated 🎉
• TCL_ERROR means an error happened while evaluating the expression 😭

if TCL_ERROR comes back, then you can grab a message describing the error using Tcl_GetObjResult. and lowkey important: if an error happens while executing a Tcl command that's embedded inside the expression, then that error is what gets returned. it propagates, periodt.

if the expression evaluates fine, then its value comes back in one of four forms, depending on which procedure you called:

• Tcl_ExprLongObj stores an integer value at *longPtr. if the expression's actual value is a floating-point number, it gets truncated to an integer (yes, chopped, no rounding romance). and if the expression's actual value is a non-numeric string, you get an error. sorry bestie.
• Tcl_ExprDoubleObj stores a floating-point value at *doublePtr. if the expression's actual value is an integer, it gets converted to floating-point. if it's a non-numeric string, error again, no exceptions.
• Tcl_ExprBooleanObj stores a 0/1 integer value at *booleanPtr. if the expression's actual value is an integer or a floating-point number, then it stores 0 at *booleanPtr if the value was zero, and 1 otherwise. if the expression's actual value is a non-numeric string, then it has to be one of the values accepted by Tcl_GetBoolean — things like “yes” or “no” — or else an error occurs.
• Tcl_ExprObj, if it successfully evaluates the expression, stores a pointer to the Tcl value containing the expression's value at *resultPtrPtr. and this is the part where you have to be a responsible main character: the caller is responsible for calling Tcl_DecrRefCount to decrement the value's reference count once they're done with the value. do not forget her. she will leak. 💀

---

🦋 REFERENCE COUNT MANAGEMENT 🦋

Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, and Tcl_ExprObj all increment and decrement the reference count of their objPtr arguments.

so listen: you must not pass them any value with a reference count of zero. that's a hard no.

they also manipulate the interpreter result — which means you must not count on the interpreter result to hold the reference count of any value across these calls. don't do it. she's not holding it for you. 🙈

---

🌈 SEE ALSO 🌈

• Tcl_ExprLong
• Tcl_ExprDouble
• Tcl_ExprBoolean
• Tcl_ExprString
• Tcl_GetObjResult

---

👑 KEYWORDS 👑

boolean, double, evaluate, expression, integer, value, string

---

and that's the whole page bestie, go evaluate something iconic 💖✨

this was Tcl_ExprLongObj(3tcl), living in the Tcl library procedures, version 8.0 — mwah, stan forever 🫶🌸