DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_SetIntObj(3tcl)




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_GetLongFromObj,
     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                     Last change: 8.5                        1

Tcl_IntObj(3)        Tcl Library Procedures         Tcl_IntObj(3)

     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 initialize or
                                           set a Tcl object.

     Tcl_WideInt wideValue (in)            Wide   integer   value
                                           used  to initialize or
                                           set a Tcl object.

     Tcl_Obj *objPtr (in/out)              For     Tcl_SetIntObj,
                                           Tcl_SetLongObj,
                                           Tcl_SetWideIntObj, and
                                           Tcl_SetBignumObj, this
                                           points to  the  object
                                           in  which  to store an
                                           integral  value.   For
                                           Tcl_GetIntFromObj,
                                           Tcl_GetLongFromObj,
                                           Tcl_GetWideIntFromObj,
                                           Tcl_GetBignumFromObj,
                                           and
                                           Tcl_TakeBignumFromObj,
                                           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.

Tcl                     Last change: 8.5                        2

Tcl_IntObj(3)        Tcl Library Procedures         Tcl_IntObj(3)

     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  |
     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  stan-  |
     dard.  The Tcl_WideInt type is a typedef defined to be what-  |
     ever 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  |
     object initialized to the integral value  of  the  argument.  |
     The returned Tcl object is unshared.                          |

     The Tcl_SetIntObj,  Tcl_SetLongObj,  Tcl_SetWideIntObj,  and  |
     Tcl_SetBignumObj  routines each set the value of an existing  |
     Tcl object pointed to by objPtr to the integral  value  pro-  |
     vided 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 policy.  |
     Any existing string representation or  internal  representa-  |
     tion  in  the  unshared Tcl object will be freed as a conse-  |
     quence 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  |

Tcl                     Last change: 8.5                        3

Tcl_IntObj(3)        Tcl Library Procedures         Tcl_IntObj(3)

     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 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  any-  |
     thing  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 object, integer type, internal  representa-
     tion, object, object type, string representation

Tcl                     Last change: 8.5                        4


Man(1) output converted with man2html