Tcl_DoubleObj(3)

💖 Tcl_DoubleObj — bestie edition 💖

okay so this is a page from the Tcl Library Procedures manual, and it's filed under Tcl_DoubleObj(3). it's all about the three little functions that let you push floating-point numbers around inside Tcl values. grab a snack, we're going in 🍓

---

✨ NAME ✨

Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj — manipulate Tcl values as floating-point values 💅

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

Tcl_Obj *
Tcl_NewDoubleObj(doubleValue)

Tcl_SetDoubleObj(objPtr, doubleValue)

int
Tcl_GetDoubleFromObj(interp, objPtr, doublePtr)

---

🦋 ARGUMENTS 🦋

• double doubleValue (in) — a double-precision floating-point value that gets used to initialize or set a Tcl value. it's giving "the number you actually care about" ✨
• Tcl_Obj *objPtr (in/out) — for Tcl_SetDoubleObj, this points to the value you're storing a double into. for Tcl_GetDoubleFromObj, this is the value you're pulling a double out of. same pointer, two very different jobs, main character energy tbh 👑
• Tcl_Interp *interp (in/out) — when it's non-NULL, an error message gets left here if retrieving the double value fails. basically the designated spot for bad news 📢
• double *doublePtr (out) — points to the place where the double value you got from objPtr gets stored. the lil drop-off box 🎀

---

💜 DESCRIPTION 💜

so these procedures are the whole toolkit for creating, modifying, and reading Tcl values that hold double-precision floating-point values. three functions, one vibe, no cap.

Tcl_NewDoubleObj creates and returns a brand new Tcl value initialized to the double value doubleValue. and bestie, listen — the returned Tcl value is unshared. fresh out the box, zero friends, just how Tcl likes it 🫶

Tcl_SetDoubleObj sets the value of an existing Tcl value pointed to by objPtr to the double value doubleValue. the objPtr argument must point to an unshared Tcl value. like, for real. any attempt to set the value of a shared Tcl value violates Tcl's copy-on-write policy — that's a whole rules-are-rules situation, do not test it 💀. and as a consequence of setting the new value, any existing string representation or internal representation hanging out in that unshared Tcl value gets freed. bye girl, you had a good run 👋

Tcl_GetDoubleFromObj attempts to retrieve a double value from the Tcl value objPtr. here's how it goes down:

• if the attempt succeeds, then TCL_OK is returned, and the double value is written to the storage pointed to by doublePtr. slay ✅
• if the attempt fails, then TCL_ERROR is returned, and if interp is non-NULL, an error message is left in interp. not slay, but informative 😭

also, the Tcl_ObjType of objPtr may be changed, which makes subsequent calls to Tcl_GetDoubleFromObj more efficient. it's literally leveling up so next time hits different 🔥

---

💅 REFERENCE COUNT MANAGEMENT 💅

okay this part matters so pay attention, this is the iykyk section:

• Tcl_NewDoubleObj always returns a zero-reference object, much like Tcl_NewObj. you own it now, bestie, act accordingly.
• Tcl_SetDoubleObj does not modify the reference count of its objPtr argument — but it does require that the object be unshared. no touching the refcount, yes respecting the unshared rule.
• Tcl_GetDoubleFromObj does not modify the reference count of its objPtr argument either; it only reads. but — and this is the plot twist — this function may set the interpreter result, and if that's the only place holding a reference to the object, then it will be deleted. 💀 gone. so heads up on that one, fr fr.

⚠️ warning from your girl: that last bullet is a sneaky one. reading can delete. keep a reference if you need the object to survive. 🙈

---

🌈 SEE ALSO 🌈

• Tcl_NewObj
• Tcl_DecrRefCount
• Tcl_IncrRefCount
• Tcl_GetObjResult

---

⭐ KEYWORDS ⭐

double, double value, double type, internal representation, value, value type, string representation

---

and that's the whole page, bestie, you ate it up 💖 this was written against Tcl 8.0 and it's the Tcl_DoubleObj(3) manual page — go forth and handle your doubles responsibly, mwah 🎀✨🦋