Tcl_SubstObj(3)

💖 Tcl_SubstObj — bestie edition 💖

okay so this is one of the Tcl Library Procedures, and we're about to do substitutions on Tcl values. it's giving subst but make it C. no cap. ✨

---

✨ NAME ✨

Tcl_SubstObj — perform substitutions on Tcl values 🎀

---

🦋 SYNOPSIS 🦋

#include <tcl.h>

Tcl_Obj *
Tcl_SubstObj(interp, objPtr, flags)

---

🌸 ARGUMENTS 🌸

• Tcl_Interp *interp (in) — the interpreter where we're gonna run Tcl scripts and look up variables. if something goes wrong, the interpreter's result gets rewritten to hold an error message. so like, she tells you when it's bad. 💅
• Tcl_Obj *objPtr (in) — a Tcl value holding the string we're doing substitutions on. the main character of this whole operation fr.
• int flags (in) — an OR'ed combination of flag bits that say which substitutions to perform. the supported ones rn are TCL_SUBST_COMMANDS, TCL_SUBST_VARIABLES and TCL_SUBST_BACKSLASHES, and then there's TCL_SUBST_ALL which is literally just there as a convenience for the super common case where you want all the substitutions. queen behavior honestly. 👑

---

💜 DESCRIPTION 💜

Tcl_SubstObj performs substitutions on strings, in the exact fashion of the subst command. it grabs the value of the string sitting inside objPtr and scans it, copying characters and doing the chosen substitutions as it goes, into an output value — and that output value is what gets returned as the result of the function. 🫶

but bestie, if an error happens during a command or variable substitution, the function returns NULL and an error message is left in interp's result. not the vibe, but at least you know.

three kinds of substitutions are supported, and here's the tea:

• when the TCL_SUBST_BACKSLASHES bit is set in flags, sequences that look like backslash substitutions for Tcl commands get replaced by their corresponding character. 🪄
• when the TCL_SUBST_VARIABLES bit is set in flags, sequences that look like variable substitutions for Tcl commands get replaced by the contents of the named variable. 📦
• when the TCL_SUBST_COMMANDS bit is set in flags, sequences that look like command substitutions for Tcl commands get replaced by the result of evaluating that script. and here's where it gets spicy 🌶️ — where an uncaught "continue exception" occurs during the evaluation of a command substitution, an empty string is substituted for the command. but where an uncaught "break exception" occurs during the evaluation of a command substitution, the result of the whole substitution on objPtr gets truncated at the point immediately before the start of the command substitution — and no characters get added to the result, and no substitutions get performed after that point. she just stops. periodt. 💀

---

👑 REFERENCE COUNT MANAGEMENT 👑

okay this part is important, don't scroll past it 🙈

the objPtr argument to Tcl_SubstObj must not have a reference count of zero. this function modifies the interpreter result, both on success and on failure. the result of this function on success is exactly the current interpreter result. and if you wanna hold onto a successful result, you should increment its reference count. that's the whole rule. love that for us. ✨

---

🌈 SEE ALSO 🌈

• subst(n)

---

⭐ KEYWORDS ⭐

backslash substitution, command substitution, variable substitution

---

and that's the page, bestie!! this one's from Tcl 8.4, the Tcl_SubstObj(3) era of the Tcl Library Procedures, so go forth and substitute responsibly 💖✨🎀🦋💅