Tcl_DoubleObj(3tcl)

💖 Tcl_DoubleObj — the double-precision era 💖

okay bestie, this is Tcl_DoubleObj(3tcl) from the Tcl Library Procedures, and it's literally the whole tutorial on how to make, poke at, and read Tcl values that are holding floating-point (double-precision) numbers. it's giving ✨math girlie✨ and honestly? iconic.

---

✨ 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's used to initialize or set a Tcl value. it's the number you're bringing to the party 💅
• Tcl_Obj *objPtr (in/out) — for Tcl_SetDoubleObj, this points to the value you're storing a double into. for Tcl_GetDoubleFromObj, this refers to the value you're retrieving a double from. so it's the same pointer, different direction of vibes 🔄
• Tcl_Interp *interp (in/out) — when it's non-NULL, an error message gets dropped here when double value retrieval fails. so if things go wrong, she's the one holding the receipts 📝
• double *doublePtr (out) — points to the place where the double value obtained from objPtr gets stored. it's the lil landing pad 🛬

---

💜 DESCRIPTION 💜

these procedures are your whole toolkit for creating, modifying, and reading Tcl values that hold double-precision floating-point values. three besties, three jobs, no cap.

Tcl_NewDoubleObj creates and returns a brand new Tcl value initialized to the double value doubleValue. the returned Tcl value is unshared — it's fresh out the box, nobody else is holding it, main character energy only 👑

Tcl_SetDoubleObj sets the value of an existing Tcl value pointed to by objPtr to the double value doubleValue. but — and listen carefully bestie — the objPtr argument must point to an unshared Tcl value. any attempt to set the value of a shared Tcl value violates Tcl's copy-on-write policy. 🚨 not a vibe, don't do it. and also, any existing string representation or internal representation in that unshared Tcl value will be freed as a consequence of setting the new value. like, gone. released. the old rep does not get to stay 💀

Tcl_GetDoubleFromObj attempts to retrieve a double value from the Tcl value objPtr. if the attempt succeeds, then TCL_OK is returned, and the double value is written to the storage pointed to by doublePtr ✨ success slay. if the attempt fails, then TCL_ERROR is returned, and if interp is non-NULL, an error message is left in interp 😭 also, heads up: the Tcl_ObjType of objPtr may be changed, which makes subsequent calls to Tcl_GetDoubleFromObj more efficient. glow-up for future you 🦋

---

🌈 REFERENCE COUNT MANAGEMENT 🌈

this is the part where we count our blessings (and our references) 🙏

• Tcl_NewDoubleObj always returns a zero-reference object, much like Tcl_NewObj. baby starts at zero, that's just how she arrives 🍼
• Tcl_SetDoubleObj does not modify the reference count of its objPtr argument, but it does require that the object be unshared. so like, don't touch the count, but do make sure nobody else is holding it 👀
• Tcl_GetDoubleFromObj does not modify the reference count of its objPtr argument; it only reads. it's just looking respectfully 🙈 note however that this function may set the interpreter result; if that is the only place that is holding a reference to the object, it will be deleted. yes, really. read-only doesn't mean the object is safe forever, bestie, keep an eye on it 💅

---

👑 SEE ALSO 👑

Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult — go read those next, they're the extended universe 🌌

---

⭐ KEYWORDS ⭐

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

---

and that's the whole page, no notes 💖 this one shipped with Tcl 8.0, and it lives at Tcl_DoubleObj(3tcl) — so when you're deep in the C API at 3am and everything is doubles, you know exactly where to find me. mwah, go write some unshared objects 🎀✨🫶