Provided by: tcl8.6-doc_8.6.13+dfsg-2_all 
NAME
Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj,
Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj,
Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj -
manipulate Tcl values as integers
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 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_Obj *objPtr (in/out) For Tcl_SetIntObj, Tcl_SetLongObj,
Tcl_SetWideIntObj, 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_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 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
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 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_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, 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_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, 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.
SEE ALSO
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
KEYWORDS
integer, integer value, integer type, internal representation, value, value type, string
representation