Tcl\_IntObj(3) Tcl Library Procedures Tcl\_IntObj(3) ``` ``` # [NAME](#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 # [SYNOPSIS](#SYNOPSIS) ``` #include 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 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](#ARGUMENTS) Tcl\_Size *endValue* (in) **Tcl\_GetIntForIndex** will return this when the input value is "end". int *intValue* (in) Integer value used to initialize or set a Tcl value. long *longValue* (in) Long integer value used to initialize or set a Tcl value. Tcl\_WideInt *wideValue* (in) Wide integer value used to initialize or set a Tcl value. Tcl\_WideUInt *uwideValue* (in) 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 in which to store an integral value. For **Tcl\_GetIntFromObj**, **Tcl\_GetLongFromObj**, **Tcl\_GetWideIntFromObj**, **Tcl\_GetBignumFromObj**, and **Tcl\_TakeBignumFromObj**, this refers to the value from which to retrieve an integral value. Tcl\_Interp *\*interp* (in/out) When non-NULL, an error message is left here when integral value retrieval fails. int *\*intPtr* (out) Points to place to store the integer value retrieved from *objPtr*. long *\*longPtr* (out) Points to place to store the long integer value retrieved from *objPtr*. Tcl\_Size *\*indexPtr* (out) Points to place to store the Tcl\_Size value retrieved from *objPtr*. Tcl\_WideInt *\*widePtr* (out) Points to place to store the wide integer value retrieved from *objPtr*. Tcl\_WideUInt *\*uwidePtr* (out) Points to place to store the unsigned wide integer value retrieved from *objPtr*. Tcl\_Size *\*sizePtr* (out) Points to 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. double *doubleValue* (in) Double value from which the integer part is determined and used to initialize a multi-precision integer value. ``` ``` # [DESCRIPTION](#DESCRIPTION) These procedures are used to create, modify, and read Tcl values that hold integral values. The different routines exist to accommodate different integral types in C with which values might be exchanged. The C integral types for which Tcl provides value exchange routines 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. 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 new Tcl value initialized to the integral value of the argument. The returned Tcl value is unshared. 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. Any existing string representation or internal representation in the unshared Tcl value will be freed as a consequence of setting the new value. 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. 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. 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. 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. 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*. # [REFERENCE COUNT MANAGEMENT](#REFERENCE_COUNT_MANAGEMENT) **Tcl\_NewIntObj**, **Tcl\_NewLongObj**, **Tcl\_NewWideIntObj**, and **Tcl\_NewBignumObj** always return a zero-reference object, much like **Tcl\_NewObj**. **Tcl\_SetIntObj**, **Tcl\_SetLongObj**, **Tcl\_SetWideIntObj**, and **Tcl\_SetBignumObj** do not modify the reference count of their *objPtr* arguments, but 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](#SEE_ALSO) Tcl\_NewObj, Tcl\_DecrRefCount, Tcl\_IncrRefCount, Tcl\_GetObjResult # [KEYWORDS](#KEYWORDS) integer, integer value, integer type, internal representation, value, value type, string representation 8.5 Tcl --- Document: Tcl_SetBignumObj(3) from tcl 9.1.0-r1 (Chainguard OS) Source: https://downloads.sourceforge.net/project/tcl/Tcl/9.1.0/tcl9.1.0-src.tar.gz