Tcl_IntObj(3) Tcl Library Procedures Tcl_IntObj(3)______________________________________________________________________________NAME
Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj,
Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFro‐
mObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj,
Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj - manipulate Tcl objects as
integer values
SYNOPSIS
#include <tcl.h>
Tcl_Obj *
Tcl_NewIntObj(intValue)
Tcl_Obj *
Tcl_NewLongObj(longValue)
Tcl_Obj *
Tcl_NewWideIntObj(wideValue)
Tcl_SetIntObj(objPtr, intValue)
Tcl_SetLongObj(objPtr, longValue)
Tcl_SetWideIntObj(objPtr, wideValue)
int
Tcl_GetIntFromObj(interp, objPtr, intPtr)
int
Tcl_GetLongFromObj(interp, objPtr, longPtr)
int
Tcl_GetWideIntFromObj(interp, objPtr, widePtr)
#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
int intValue (in) Integer value used to initialize
or set a Tcl object.
long longValue (in) Long integer value used to ini‐
tialize or set a Tcl object.
Tcl_WideInt wideValue (in) Wide integer value used to ini‐
tialize or set a Tcl object.
Tcl_Obj *objPtr (in/out) For Tcl_SetIntObj, Tcl_SetLon‐
gObj, Tcl_SetWideIntObj, and
Tcl_SetBignumObj, this points to
the object in which to store an
integral value. For Tcl_GetInt‐
FromObj, Tcl_GetLongFromObj,
Tcl_GetWideIntFromObj, Tcl_Get‐
BignumFromObj, and Tcl_Take‐
BignumFromObj, this refers to the
object 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_WideInt *widePtr (out) Points to place to store the wide
integer value retrieved from
objPtr.
mp_int *bigValue (in/out) Points to a multi-precision inte‐ │
ger structure declared by the │
LibTomMath library.
double doubleValue (in) Double value from which the inte‐ │
ger part is determined and used │
to initialize a multi-precision │
integer value.
_________________________________________________________________DESCRIPTION
These procedures are used to create, modify, and read Tcl objects 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 plat‐ │
form and the C compiler, the actual type might be long int, long long │
int, int64, or something else. 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, and Tcl_NewBignu‐ │
mObj routines each create and return a new Tcl object initialized to │
the integral value of the argument. The returned Tcl object is │
unshared. │
The Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, and Tcl_SetBignu‐ │
mObj routines each set the value of an existing Tcl object pointed to │
by objPtr to the integral value provided by the other argument. The │
objPtr argument must point to an unshared Tcl object. Any attempt to │
set the value of a shared Tcl object violates Tcl's copy-on-write pol‐ │
icy. Any existing string representation or internal representation in │
the unshared Tcl object will be freed as a consequence of setting the │
new value. │
The Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, │
Tcl_GetBignumFromObj, and Tcl_TakeBignumFromObj routines attempt to │
retrieve an integral value of the appropriate type from the Tcl object │
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 sub‐ │
sequent calls to the same routine more efficient. Unlike the other │
functions, Tcl_TakeBignumFromObj may set the content of the Tcl object │
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_GetBignum‐ │
FromObj 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.
SEE ALSO
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
KEYWORDS
integer, integer object, integer type, internal representation, object,
object type, string representation
Tcl 8.5 Tcl_IntObj(3)