Tcl_GetNumber(3)

💖 Tcl_GetNumber — the Tcl Library Procedures glow-up 💖

okay bestie, sit down, hydrate, and let me tell you about two little functions that pull actual numbers out of Tcl values. this is Tcl_GetNumber(3) from the Tcl Library Procedures and it's genuinely so useful, no cap.

---

✨ NAME ✨

Tcl_GetNumber, Tcl_GetNumberFromObj — get a numeric value out of a Tcl value. that's it, that's the whole job 🫶

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

#include <tclTomMath.h>

int
Tcl_GetNumber(interp, bytes, numBytes, clientDataPtr, typePtr)

int
Tcl_GetNumberFromObj(interp, objPtr, clientDataPtr, typePtr)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (out) — when it's not NULL, error info gets recorded here whenever the value isn't in any of the numeric formats Tcl recognizes. basically the lil diary where the error goes 📓
• const char *bytes (in) — points to the first byte of the string value we're examining. first byte, bestie, that's where it starts.
• Tcl_Size numBytes (in) — how many bytes, starting at bytes, we should examine. and if numBytes is negative?? then we examine all the bytes until the first NUL byte stops us. so negative = "just keep going till the NUL, queen" 💅
• void * *clientDataPtr (out) — points to a space where a pointer value can be written. through that pointer, a numeric value is available to read. it's giving middle-man, but make it useful.
• int *typePtr (out) — points to a space where a value can be written that reports what type of numeric storage is available to read. the vibe check of types, fr fr.
• Tcl_Obj *objPtr (in) — a Tcl value to be examined. the subject of the investigation 🔍

---

🦋 DESCRIPTION 🦋

so these procedures let callers retrieve a numeric value from a Tcl value, in a numeric format that Tcl recognizes. simple concept, iconic execution.

Tcl recognizes many values as numbers. some examples, and yes these are exact: "0", " +1", "-2 ", " 3 ", "0xdad1", "0d09", "1_000_000", "4.0", "1e-7", "NaN", or "Inf". look at that range. look at the flexibility. we love a versatile parser. 🥰

when built-in Tcl commands act on these values as numbers, they get converted to a numeric representation so C code can handle them efficiently. Tcl uses three C types to store these representations:

1. double — provided by the C language standard.
2. Tcl_WideInt — declared in the Tcl header file tcl.h, and equivalent to the C standard type long long on most platforms.
3. mp_int — declared in the header file tclTomMath.h, and implemented by the LibTomMath multiple-precision integer library, which is included with Tcl.

three types, one slay ✨

---

🌈 the two routines are twins, actually

The routines Tcl_GetNumber and Tcl_GetNumberFromObj perform the same function. the only difference is how the arguments hand them the Tcl value to examine.

• Tcl_GetNumber accepts a counted string value in the arguments bytes and numBytes — or a NUL-terminated string value when numBytes is negative.
• Tcl_GetNumberFromObj accepts the Tcl value in objPtr.

both of them examine the Tcl value and figure out whether Tcl recognizes it as a number. if not, both return TCL_ERROR and — when interp is not NULL — record an error message and an error code in interp. sad girl hours 😭

if Tcl does recognize the examined value as a number, both return TCL_OK, and use the pointer arguments clientDataPtr and typePtr (which may not be NULL) to report info the caller can use to retrieve the numeric representation. both routines write to *clientDataPtr a pointer to the internal storage location where Tcl holds the converted numeric value. it's giving backstage pass 🎟️

---

💜 when it's stored as a double

a call to the math library routine isnan determines whether that value is not a number (NaN).

• if it is NaN, both Tcl_GetNumber and Tcl_GetNumberFromObj write the value TCL_NUMBER_NAN to *typePtr.
• if it is not, both routines write the value TCL_NUMBER_DOUBLE to *typePtr.

why two different type values for basically the same storage? because Tcl_GetDoubleFromObj raises an error on NaN values, bestie. that's the whole reason. for both reported type values, the storage pointer may be cast to type const double * and the double numeric value may be read through it.

---

👑 when it's stored as a Tcl_WideInt

both Tcl_GetNumber and Tcl_GetNumberFromObj write the value TCL_NUMBER_INT to *typePtr. the storage pointer may be cast to type const Tcl_WideInt * and the Tcl_WideInt numeric value may be read through it. clean, simple, main character energy.

---

🍓 when it's stored as an mp_int

both Tcl_GetNumber and Tcl_GetNumberFromObj write the value TCL_NUMBER_BIG to *typePtr. the storage pointer may be cast to type const mp_int * and the mp_int numeric value may be read through it. big number? big type value. consistency, we adore her.

---

🔮 future-proofing (iykyk)

Future releases of Tcl might expand or revise the recognition of values as numbers. if additional storage representations get adopted, these routines will add new values to be written to *typePtr to identify them. so callers should consider how they should react to unknown values written to *typePtr. don't hard-code your assumptions, bestie, that's the lesson 🙈

---

💀 the part where you have to be careful

when callers of these routines read numeric values through the reported storage pointer, they are accessing memory that belongs to the Tcl library. and the Tcl library has the power to overwrite or free this memory. the storage pointer reported by a call to Tcl_GetNumber or Tcl_GetNumberFromObj should not be used after the same thread has possibly returned control to the Tcl library. if you need longer term access to the numeric value, copy it into memory controlled by the caller.

⚠️ and callers must not attempt to write through or free the storage pointer. that memory is not yours. do not touch. do not free. do not be that girl. 💅

---

🌟 SEE ALSO 🌟

Tcl_GetDouble, Tcl_GetDoubleFromObj, Tcl_GetWideIntFromObj

---

⭐ KEYWORDS ⭐

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

---

okay that's the whole page, you ate it, you understood it, you're basically a Tcl internals girlie now 🧚 this was Tcl_GetNumber(3) from the Tcl Library Procedures, Tcl version 9.0 — mwah, go forth and read your numbers responsibly 💖✨🎀