1Tcl_IntObj(3) Tcl Library Procedures Tcl_IntObj(3)
2______________________________________________________________________________
6
8 Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj,
9 Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFro‐
10 mObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj,
11 Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj - manipulate Tcl objects as
12 integer values
13
15 #include <tcl.h>
16 Tcl_Obj *
18 Tcl_NewIntObj(intValue)
19 Tcl_Obj *
21 Tcl_NewLongObj(longValue)
22 Tcl_Obj *
24 Tcl_NewWideIntObj(wideValue)
25 Tcl_SetIntObj(objPtr, intValue)
27 Tcl_SetLongObj(objPtr, longValue)
29 Tcl_SetWideIntObj(objPtr, wideValue)
31 int
33 Tcl_GetIntFromObj(interp, objPtr, intPtr)
34 int
36 Tcl_GetLongFromObj(interp, objPtr, longPtr)
37 int
39 Tcl_GetWideIntFromObj(interp, objPtr, widePtr)
40 #include <tclTomMath.h> │
43 Tcl_Obj * │
45 Tcl_NewBignumObj(bigValue) │
46 Tcl_SetBignumObj(objPtr, bigValue) │
48 int │
50 Tcl_GetBignumFromObj(interp, objPtr, bigValue) │
51 int │
53 Tcl_TakeBignumFromObj(interp, objPtr, bigValue) │
54 int │
56 Tcl_InitBignumFromDouble(interp, doubleValue, bigValue) │
57
59 int intValue (in) Integer value used to initialize
60 or set a Tcl object.
61 long longValue (in) Long integer value used to ini‐
63 tialize or set a Tcl object.
64 Tcl_WideInt wideValue (in) Wide integer value used to ini‐
66 tialize or set a Tcl object.
67 Tcl_Obj *objPtr (in/out) For Tcl_SetIntObj, Tcl_SetLon‐
69 gObj, Tcl_SetWideIntObj, and
70 Tcl_SetBignumObj, this points to
71 the object in which to store an
72 integral value. For Tcl_GetInt‐
73 FromObj, Tcl_GetLongFromObj,
74 Tcl_GetWideIntFromObj, Tcl_Get‐
75 BignumFromObj, and Tcl_Take‐
76 BignumFromObj, this refers to the
77 object from which to retrieve an
78 integral value.
79 Tcl_Interp *interp (in/out) When non-NULL, an error message
81 is left here when integral value
82 retrieval fails.
83 int *intPtr (out) Points to place to store the
85 integer value retrieved from
86 objPtr.
87 long *longPtr (out) Points to place to store the long
89 integer value retrieved from
90 objPtr.
91 Tcl_WideInt *widePtr (out) Points to place to store the wide
93 integer value retrieved from
94 objPtr.
95 mp_int *bigValue (in/out) Points to a multi-precision inte‐ │
97 ger structure declared by the │
98 LibTomMath library.
99 double doubleValue (in) Double value from which the inte‐ │
101 ger part is determined and used │
102 to initialize a multi-precision │
103 integer value.
104_________________________________________________________________
105
108 These procedures are used to create, modify, and read Tcl objects that │
109 hold integral values. │
110 The different routines exist to accomodate different integral types in │
112 C with which values might be exchanged. The C integral types for which │
113 Tcl provides value exchange routines are int, long int, Tcl_WideInt, │
114 and mp_int. The int and long int types are provided by the C language │
115 standard. The Tcl_WideInt type is a typedef defined to be whatever │
116 signed integral type covers at least the 64-bit integer range │
117 (-9223372036854775808 to 9223372036854775807). Depending on the plat‐ │
118 form and the C compiler, the actual type might be long int, long long │
119 int, int64, or something else. The mp_int type is a multiple-precision │
120 integer type defined by the LibTomMath multiple-precision integer │
121 library. │
122 The Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, and Tcl_NewBignu‐ │
124 mObj routines each create and return a new Tcl object initialized to │
125 the integral value of the argument. The returned Tcl object is │
126 unshared. │
127 The Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, and Tcl_SetBignu‐ │
129 mObj routines each set the value of an existing Tcl object pointed to │
130 by objPtr to the integral value provided by the other argument. The │
131 objPtr argument must point to an unshared Tcl object. Any attempt to │
132 set the value of a shared Tcl object violates Tcl's copy-on-write pol‐ │
133 icy. Any existing string representation or internal representation in │
134 the unshared Tcl object will be freed as a consequence of setting the │
135 new value. │
136 The Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, │
138 Tcl_GetBignumFromObj, and Tcl_TakeBignumFromObj routines attempt to │
139 retrieve an integral value of the appropriate type from the Tcl object │
140 objPtr. If the attempt succeeds, then TCL_OK is returned, and the │
141 value is written to the storage provided by the caller. The attempt │
142 might fail if objPtr does not hold an integral value, or if the value │
143 exceeds the range of the target type. If the attempt fails, then │
144 TCL_ERROR is returned, and if interp is non-NULL, an error message is │
145 left in interp. The Tcl_ObjType of objPtr may be changed to make sub‐ │
146 sequent calls to the same routine more efficient. Unlike the other │
147 functions, Tcl_TakeBignumFromObj may set the content of the Tcl object │
148 objPtr to an empty string in the process of retrieving the multiple- │
149 precision integer value. │
150 The choice between Tcl_GetBignumFromObj and Tcl_TakeBignumFromObj is │
152 governed by how the caller will continue to use objPtr. If after the │
153 mp_int value is retrieved from objPtr, the caller will make no more use │
154 of objPtr, then using Tcl_TakeBignumFromObj permits Tcl to detect when │
155 an unshared objPtr permits the value to be moved instead of copied, │
156 which should be more efficient. If anything later in the caller │
157 requires objPtr to continue to hold the same value, then Tcl_GetBignum‐ │
158 FromObj must be chosen. │
159 The Tcl_InitBignumFromDouble routine is a utility procedure that │
161 extracts the integer part of doubleValue and stores that integer value │
162 in the mp_int value bigValue.
163
165 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
166
168 integer, integer object, integer type, internal representation, object,
169 object type, string representation
170Tcl 8.5 Tcl_IntObj(3)