Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  in-
					     teger  value  retrieved  from ob-
					     jPtr.

       long *longPtr (out)		     Points to place to	store the long
					     integer  value retrieved from ob-
					     jPtr.

       Tcl_WideInt *widePtr (out)	     Points to place to	store the wide
					     integer  value retrieved from ob-
					     jPtr.

       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 li- |
       brary.								       |

       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  un- |
       shared.								       |

       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 re- |
       trieve 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 re- |
       quires objPtr to	continue to hold the same value,  then	Tcl_GetBignum- |
       FromObj must be chosen.						       |

       The  Tcl_InitBignumFromDouble  routine  is a utility procedure that ex- |
       tracts 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)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_GetBignumFromObj.tcl85&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help