Tcl_ExprLongObj(3)

💖 Tcl_ExprLongObj — bestie, let's evaluate an expression 💖

okay so. this one lives in the Tcl library procedures corner of the man-page universe (Tcl_ExprLongObj(3)), and it's basically the four-way girlboss squad of expression evaluation. four functions, one job: run an expression, hand you back the answer in whatever shape you asked for. periodt.

---

✨ NAME ✨

Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj — evaluate an expression. that's it, that's the whole personality. 💅

---

🌸 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 whose little context we're evaluating objPtr inside of. she's the main character here.
• Tcl_Obj *objPtr (in) — pointer to a value that's holding the expression you wanna evaluate. like, the expression itself is chilling inside this object.
• long *longPtr (out) — pointer to the spot where we're gonna drop the integer value of the expression. 🫶
• int *doublePtr (out) — pointer to the spot where the floating-point value of the expression goes. yes bestie, the type really is int * in the signature — that's what it says, don't come for me.
• int *booleanPtr (out) — pointer to the spot that receives the 0/1 boolean value of the expression.
• Tcl_Obj **resultPtrPtr (out) — pointer to the spot where we stash a pointer to the value that is the result of the expression. double pointer, double the drama, iykyk. ✨

---

💜 DESCRIPTION 💜

So these four procedures all evaluate an expression, but each one gives you the result in a different form. four flavors, one vibe. the expression comes in through the objPtr argument, and it can take any of the forms that the expr command accepts — so if expr can do it, so can this. 💅

The interp argument points at the interpreter used to evaluate the expression (think: for variables and nested Tcl commands, yes those too) and also to hand back any error info. she does both jobs, iconic behavior.

For all four of these procedures, the return value is a standard Tcl result: TCL_OK means the expression was successfully evaluated 🎉 and TCL_ERROR means something went wrong while evaluating it 😭. If TCL_ERROR comes back at you, you can go grab a message describing the error with Tcl_GetObjResult. and lowkey important: if an error happens while executing a Tcl command embedded inside the expression, then that error is what gets returned. no hiding it, no rerouting it.

If the expression evaluates successfully, 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, truncated, not rounded, don't @ me). and if the expression's actual value is a non-numeric string? error. straight up. 🚫
• Tcl_ExprDoubleObj stores a floating-point value at *doublePtr. if the expression's actual value is an integer, it gets converted to floating-point — glow up. if it's a non-numeric string, again: error.
• 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 they store 0 at *booleanPtr when 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 that Tcl_GetBoolean accepts — stuff like “yes” or “no” — or else an error occurs. no random strings allowed bestie, vibe check failed. 💀
• Tcl_ExprObj, if it successfully evaluates the expression, stores a pointer to the Tcl value holding the expression's value at *resultPtrPtr. and in that case, you (the caller) are responsible for calling Tcl_DecrRefCount to decrement the value's reference count once you're done with it. it's giving "you break it, you bought it." 🔥

---

🦋 REFERENCE COUNT MANAGEMENT 🦋

Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, and Tcl_ExprObj all increment and decrement the reference count of their objPtr arguments. so, real talk: you must not pass them any value that has a reference count of zero. like, ever. 🙈

They also manipulate the interpreter result, so you must not count on the interpreter result to hold the reference count of any value across these calls. don't do it, don't assume it, just let it be. ✨

---

🌈 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 🫶 this was Tcl 8.0 energy all the way down, dated right there in the Tcl_ExprLongObj(3) footer. go forth and evaluate responsibly. 💖✨🎀