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_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.
- 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 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 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 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
policy. 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 retrieve 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 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 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 object, integer type, internal representation, object, object
type, string representation