home | help 
Tcl_IntObj(3)		     Tcl Library Procedures		   Tcl_IntObj(3)

________________________________________________________________________________

NAME
     Tcl_NewIntObj,   Tcl_NewLongObj,	Tcl_NewWideIntObj,   Tcl_NewWideUIntObj,
     Tcl_SetIntObj,   Tcl_SetLongObj,	Tcl_SetWideIntObj,   Tcl_SetWideUIntObj,
     Tcl_GetIntFromObj,  Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetSizeInt-
     FromObj, Tcl_GetWideIntFromObj,  Tcl_GetWideUIntFromObj,  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_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 <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
     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_SetWideUIn-
					   tObj,   and	 Tcl_SetBignumObj,  this
					   points to the value in which to store
					   an integral value.	For  Tcl_GetInt-
					   FromObj,	     Tcl_GetLongFromObj,
					   Tcl_GetWideIntFromObj, Tcl_GetBignum-
					   FromObj,  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 re-
					   trieval 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 in-
					   teger 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 in-
					   teger value retrieved from objPtr.

     Tcl_WideUInt *uwidePtr (out)	   Points to place to store the unsigned
					   wide integer value retrieved from ob-
					   jPtr.

     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  ini-
					   tialize   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  stan-
     dard.   The Tcl_WideInt type is a typedef defined to be whatever signed in-
     tegral 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 type-
     def is a signed integer type  capable  of	holding  the  maximum  permitted
     lengths  of  Tcl  values  like strings and lists. Correspondingly, the pre-
     processor 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  ini-
     tialized  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 un-
     shared 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  subse-
     quent calls to the same routine more efficient.

     The  Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_Get-
     SizeIntFromObj, 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  re-
     turned, 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  gov-
     erned  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 ob-
     jPtr 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
     Tcl_NewIntObj,  Tcl_NewLongObj, Tcl_NewWideIntObj, and Tcl_NewBignumObj al-
     ways 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_GetWideInt-
     FromObj,  Tcl_GetSizeIntFromObj,  Tcl_GetBignumFromObj, and Tcl_TakeBignum-
     FromObj 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 un-
     shared 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
     Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult

KEYWORDS
     integer, integer value, integer type, internal representation, value, value
     type, string representation

Tcl				       8.5			   Tcl_IntObj(3)
home | help