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