Tcl_IntObj(3)

💖 Tcl_IntObj(3) — Tcl Library Procedures 💖

okay bestie, sit down, hydrate, because today we're learning how Tcl stores numbers. This is Tcl_IntObj from the Tcl Library Procedures manual, and it's literally the whole girl-math pipeline: making ints, setting ints, getting ints back out. No cap. 🧮✨

---

🌸 NAME 🌸

Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_NewWideUIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_SetWideUIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetSizeIntFromObj, Tcl_GetWideIntFromObj, Tcl_GetWideUIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj — manipulate Tcl values as integers. that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

#include <tcl.h>

Tcl_Obj *
Tcl_NewIntObj(intValue)

Tcl_Obj *
Tcl_NewLongObj(longValue)

Tcl_Obj *
Tcl_NewWideIntObj(wideValue)

Tcl_Obj *
Tcl_NewWideUIntObj(uwideValue)

Tcl_SetIntObj(objPtr, intValue)

Tcl_SetLongObj(objPtr, longValue)

Tcl_SetWideIntObj(objPtr, wideValue)

Tcl_SetWideUIntObj(objPtr, uwideValue)

int
Tcl_GetIntFromObj(interp, objPtr, intPtr)

int
Tcl_GetIntForIndex(interp, objPtr, endValue, indexPtr)

int
Tcl_GetLongFromObj(interp, objPtr, longPtr)

int
Tcl_GetWideIntFromObj(interp, objPtr, widePtr)

int
Tcl_GetWideUIntFromObj(interp, objPtr, uwidePtr)

int
Tcl_GetSizeIntFromObj(interp, objPtr, sizePtr)

#include <tclTomMath.h>

Tcl_Obj *
Tcl_NewBignumObj(bigValue)

Tcl_SetBignumObj(objPtr, bigValue)

int
Tcl_GetBignumFromObj(interp, objPtr, bigValue)

int
Tcl_TakeBignumFromObj(interp, objPtr, bigValue)

int
Tcl_InitBignumFromDouble(interp, doubleValue, bigValue)

---

🎀 ARGUMENTS 🎀

• Tcl_Size endValue (in) — the value Tcl_GetIntForIndex hands back when the input value is "end". it's giving "the end is a real place and it has a number". 🦋
• int intValue (in) — an integer value, used to initialize or set a Tcl value.
• long longValue (in) — a long integer value, used to initialize or set a Tcl value.
• Tcl_WideInt wideValue (in) — a wide integer value, used to initialize or set a Tcl value.
• Tcl_WideUInt uwideValue (in) — an unsigned wide integer value, used to initialize or set a Tcl value.
• Tcl_Obj *objPtr (in/out) — for Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_SetWideUIntObj, and Tcl_SetBignumObj, this points to the value where you're storing an integral value. for Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_GetBignumFromObj, and Tcl_TakeBignumFromObj, it refers to the value you're pulling an integral value out of. same pointer, two moods. 💜
• Tcl_Interp *interp (in/out) — when it's non-NULL, an error message gets dropped here if integral value retrieval fails. your little error inbox. 📥
• int *intPtr (out) — points to the place to store the integer value retrieved from objPtr.
• long *longPtr (out) — points to the place to store the long integer value retrieved from objPtr.
• Tcl_Size *indexPtr (out) — points to the place to store the Tcl_Size value retrieved from objPtr.
• Tcl_WideInt *widePtr (out) — points to the place to store the wide integer value retrieved from objPtr.
• Tcl_WideUInt *uwidePtr (out) — points to the place to store the unsigned wide integer value retrieved from objPtr.
• Tcl_Size *sizePtr (out) — points to the place to store the Tcl_Size integer value retrieved from objPtr.
• mp_int *bigValue (in/out) — points to a multi-precision integer structure declared by the LibTomMath library. big number energy, literally. 🔥
• double doubleValue (in) — a double value; the integer part gets determined from it and used to initialize a multi-precision integer value.

---

💖 DESCRIPTION 💖

these procedures create, modify, and read Tcl values that hold integral values. that's the whole job. 🫶

the different routines exist to accommodate different integral types in C, because values might get exchanged with any of them. the C integral types Tcl provides value exchange routines for are int, long int, Tcl_WideInt, and mp_int. the int and long int types are provided by the C language standard. the Tcl_WideInt type is a typedef defined to be whatever signed integral type covers at least the 64-bit integer range (-9223372036854775808 to 9223372036854775807). depending on the platform and the C compiler, the actual type might be long long int, or something else. the Tcl_Size typedef is a signed integer type capable of holding the maximum permitted lengths of Tcl values like strings and lists. and correspondingly, the preprocessor constant TCL_SIZE_MAX defines the maximum value that can be stored in a variable of this type. the mp_int type is a multiple-precision integer type defined by the LibTomMath multiple-precision integer library. 🌈

the Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_NewWideUIntObj, and Tcl_NewBignumObj routines each create and return a brand-new Tcl value initialized to the integral value of the argument. the returned Tcl value is unshared. it's fresh out the box, nobody else is holding it. ✨

the Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_SetWideUIntObj, and Tcl_SetBignumObj routines each set the value of an existing Tcl value pointed to by objPtr to the integral value provided by the other argument. 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. 😭 and any existing string representation or internal representation in the unshared Tcl value will be freed as a consequence of setting the new value. gone. freed. bye. 🦋

the Tcl_GetIntForIndex routine attempts to retrieve an index value from the Tcl value objPtr. if the attempt succeeds, then TCL_OK is returned, and the value is written to the storage provided by the caller. the attempt might fail if objPtr does not hold an index value. if the attempt fails, then TCL_ERROR is returned, and if interp is non-NULL, an error message is left in interp. the Tcl_ObjType of objPtr may be changed to make subsequent calls to the same routine more efficient. glow-up for later calls. 💅

the Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_GetSizeIntFromObj, Tcl_GetBignumFromObj, and Tcl_TakeBignumFromObj routines attempt to retrieve an integral value of the appropriate type from the Tcl value objPtr. if the attempt succeeds, then TCL_OK is returned, and the value is written to the storage provided by the caller. the attempt might fail if objPtr does not hold an integral value, or if the value exceeds the range of the target type. if the attempt fails, then TCL_ERROR is returned, and if interp is non-NULL, an error message is left in interp. the Tcl_ObjType of objPtr may be changed to make subsequent calls to the same routine more efficient. and unlike the other functions, Tcl_TakeBignumFromObj may set the content of the Tcl value objPtr to an empty string in the process of retrieving the multiple-precision integer value. yeah she empties the bag while she shops. 🛍️

the choice between Tcl_GetBignumFromObj and Tcl_TakeBignumFromObj is governed by how the caller will continue to use objPtr. if, after the mp_int value is retrieved from objPtr, the caller will make no more use of objPtr, then using Tcl_TakeBignumFromObj permits Tcl to detect when an unshared objPtr permits the value to be moved instead of copied, which should be more efficient. if anything later in the caller requires objPtr to continue to hold the same value, then Tcl_GetBignumFromObj must be chosen. no take-backs, bestie. choose wisely. 🙈

the Tcl_InitBignumFromDouble routine is a utility procedure that extracts the integer part of doubleValue and stores that integer value in the mp_int value bigValue. cute lil helper. 🎀

---

👑 REFERENCE COUNT MANAGEMENT 👑

• Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, and Tcl_NewBignumObj always return a zero-reference object, much like Tcl_NewObj. brand new, refcount zero, all yours. ⭐
• Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, and Tcl_SetBignumObj do not modify the reference count of their objPtr arguments, but they do require that the object be unshared. 👀
• Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_GetSizeIntFromObj, Tcl_GetBignumFromObj, and Tcl_TakeBignumFromObj do not modify the reference count of their objPtr arguments; they only read. 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. 💀 also note that if Tcl_TakeBignumFromObj is given an unshared value, the value of that object may be modified; it is intended to be used when the value is “consumed” by the operation at this point.

---

🌟 SEE ALSO 🌟

• Tcl_NewObj
• Tcl_DecrRefCount
• Tcl_IncrRefCount
• Tcl_GetObjResult

---

🔥 KEYWORDS 🔥

integer, integer value, integer type, internal representation, value, value type, string representation

---

okay that's the whole page, you ate it, periodt. 💅✨ this lil masterpiece is from the Tcl manual, version 8.5, filed under Tcl_IntObj(3) — go forth and manipulate some integers, bestie, you've got this. 🫶🎀🦋