Tcl_IntObj(3tcl)

💖 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

---

okay so this whole page lives in the Tcl Library Procedures manual, and its little tag is Tcl_IntObj(3tcl). it's the group chat where every single Tcl C function that turns numbers into Tcl values (and Tcl values back into numbers) hangs out. bestie, grab a snack, there's a LOT of them and they're all lowkey iconic. ✨

🌸 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) — when the value you hand to Tcl_GetIntForIndex is literally "end", this is what it hands back to you. the answer to "what even is end", basically. 💅
• int intValue (in) — the integer value you use to initialize or set a Tcl value.
• long longValue (in) — the long integer value you use to initialize or set a Tcl value.
• Tcl_WideInt wideValue (in) — the wide integer value you use to initialize or set a Tcl value.
• Tcl_WideUInt uwideValue (in) — the unsigned wide integer value you use 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 at the value you're storing an integral value into. for Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_GetBignumFromObj, and Tcl_TakeBignumFromObj, it's the value you're pulling an integral value out of. read vs write, bestie, that's the whole difference.
• Tcl_Interp *interp (in/out) — when it's not NULL, and the retrieval of an integral value fails, the error message gets dropped right here. 🫶
• int *intPtr (out) — points at the spot where the integer value retrieved from objPtr goes to live.
• long *longPtr (out) — points at the spot where the long integer value retrieved from objPtr goes to live.
• Tcl_Size *indexPtr (out) — points at the spot where the Tcl_Size value retrieved from objPtr goes to live.
• Tcl_WideInt *widePtr (out) — points at the spot where the wide integer value retrieved from objPtr goes to live.
• Tcl_WideUInt *uwidePtr (out) — points at the spot where the unsigned wide integer value retrieved from objPtr goes to live.
• Tcl_Size *sizePtr (out) — points at the spot where the Tcl_Size integer value retrieved from objPtr goes to live.
• mp_int *bigValue (in/out) — points at a multi-precision integer structure, declared by the LibTomMath library. big math energy. 🔥
• double doubleValue (in) — the double value whose integer part gets determined and then used to initialize a multi-precision integer value.

---

🦋 DESCRIPTION 🦋

so these procedures are the whole toolkit for creating, modifying, and reading Tcl values that hold integral values. that's the vibe.

the reason there are so many of them is that C has a bunch of different integral types, and values might need to be exchanged through any of them. the C integral types Tcl gives you value-exchange routines for are int, long int, Tcl_WideInt, and mp_int. the int and long int types are just handed to us by the C language standard, no drama. 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 entirely — she's flexible like that. 💅

the Tcl_Size typedef is a signed integer type that can hold the maximum permitted lengths of Tcl values like strings and lists. and the preprocessor constant TCL_SIZE_MAX defines the maximum value that can be stored in a variable of this type. so that's the ceiling, bestie.

the mp_int type is a multiple-precision integer type defined by the LibTomMath multiple-precision integer library.

✨ making new ones ✨

Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_NewWideUIntObj, and Tcl_NewBignumObj each create and return a brand new Tcl value initialized to the integral value of the argument. the returned Tcl value is unshared. fresh out the box, no cap. 🎁

✨ setting existing ones ✨

Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_SetWideUIntObj, and Tcl_SetBignumObj 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. don't do it. 🙈

any existing string representation or internal representation in the unshared Tcl value will be freed as a consequence of setting the new value. out with the old, in with the new. 💀

✨ getting an index ✨

Tcl_GetIntForIndex tries to retrieve an index value from the Tcl value objPtr. if the attempt succeeds, then TCL_OK is returned, and the value gets written to the storage the caller provided. 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 speed. ⭐

✨ getting integers out ✨

Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_GetSizeIntFromObj, Tcl_GetBignumFromObj, and Tcl_TakeBignumFromObj all try to retrieve an integral value of the appropriate type from the Tcl value objPtr.

if it works, TCL_OK comes back and the value lands in the storage the caller provided. it might fail if objPtr does not hold an integral value, or if the value exceeds the range of the target type. if it fails, TCL_ERROR comes back, 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.

👀 unlike the other functions, Tcl_TakeBignumFromObj may set the content of the Tcl value objPtr to an empty string while it's in the middle of retrieving the multiple-precision integer value. it takes, bestie. that's the whole point of the name.

the choice between Tcl_GetBignumFromObj and Tcl_TakeBignumFromObj is governed by how the caller will keep using objPtr afterwards:

• if, after the mp_int value is retrieved from objPtr, the caller makes no more use of objPtr, then using Tcl_TakeBignumFromObj lets Tcl detect when an unshared objPtr permits the value to be moved instead of copied, which should be more efficient. slay, no wasted work. 🔥
• if anything later in the caller needs objPtr to keep holding the same value, then Tcl_GetBignumFromObj must be chosen. periodt.

✨ the double-to-bignum little helper ✨

Tcl_InitBignumFromDouble is a utility procedure that extracts the integer part of doubleValue and stores that integer value in the mp_int value bigValue. tiny, but she ate. 💅

---

👑 REFERENCE COUNT MANAGEMENT 👑

okay this part is important, don't skip it.

Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, and Tcl_NewBignumObj always return a zero-reference object, much like Tcl_NewObj. brand new, refcount zero.

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

---

and that's the whole page, bestie!! this is from Tcl 8.5, and yes the page tag at the bottom is Tcl_IntObj(3tcl) — go forth and manipulate integers, you absolute icon. 🫶✨💖