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 values as
12 integers
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 value.
61 long longValue (in) Long integer value used to ini‐
63 tialize or set a Tcl value.
64 Tcl_WideInt wideValue (in) Wide integer value used to ini‐
66 tialize or set a Tcl value.
67 Tcl_Obj *objPtr (in/out) For Tcl_SetIntObj, Tcl_SetLon‐
69 gObj, Tcl_SetWideIntObj, and
70 Tcl_SetBignumObj, this points to
71 the value 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 value 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
107 These procedures are used to create, modify, and read Tcl values that
108 hold integral values.
109 The different routines exist to accommodate different integral types in
111 C with which values might be exchanged. The C integral types for which
112 Tcl provides value exchange routines are int, long int, Tcl_WideInt,
113 and mp_int. The int and long int types are provided by the C language
114 standard. The Tcl_WideInt type is a typedef defined to be whatever
115 signed integral type covers at least the 64-bit integer range
116 (-9223372036854775808 to 9223372036854775807). Depending on the plat‐
117 form and the C compiler, the actual type might be long int, long long
118 int, __int64, or something else. The mp_int type is a multiple-preci‐
119 sion integer type defined by the LibTomMath multiple-precision integer
120 library.
121 The Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, and Tcl_NewBignu‐
123 mObj routines each create and return a new Tcl value initialized to the
124 integral value of the argument. The returned Tcl value is unshared.
125 The Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, and Tcl_SetBignu‐
127 mObj routines each set the value of an existing Tcl value pointed to by
128 objPtr to the integral value provided by the other argument. The
129 objPtr argument must point to an unshared Tcl value. Any attempt to
130 set the value of a shared Tcl value violates Tcl's copy-on-write pol‐
131 icy. Any existing string representation or internal representation in
132 the unshared Tcl value will be freed as a consequence of setting the
133 new value.
134 The Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj,
136 Tcl_GetBignumFromObj, and Tcl_TakeBignumFromObj routines attempt to
137 retrieve an integral value of the appropriate type from the Tcl value
138 objPtr. If the attempt succeeds, then TCL_OK is returned, and the
139 value is written to the storage provided by the caller. The attempt
140 might fail if objPtr does not hold an integral value, or if the value
141 exceeds the range of the target type. If the attempt fails, then
142 TCL_ERROR is returned, and if interp is non-NULL, an error message is
143 left in interp. The Tcl_ObjType of objPtr may be changed to make sub‐
144 sequent calls to the same routine more efficient. Unlike the other
145 functions, Tcl_TakeBignumFromObj may set the content of the Tcl value
146 objPtr to an empty string in the process of retrieving the multiple-
147 precision integer value.
148 The choice between Tcl_GetBignumFromObj and Tcl_TakeBignumFromObj is
150 governed by how the caller will continue to use objPtr. If after the
151 mp_int value is retrieved from objPtr, the caller will make no more use
152 of objPtr, then using Tcl_TakeBignumFromObj permits Tcl to detect when
153 an unshared objPtr permits the value to be moved instead of copied,
154 which should be more efficient. If anything later in the caller
155 requires objPtr to continue to hold the same value, then Tcl_GetBignum‐
156 FromObj must be chosen.
157 The Tcl_InitBignumFromDouble routine is a utility procedure that
159 extracts the integer part of doubleValue and stores that integer value
160 in the mp_int value bigValue.
161
163 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
164
166 integer, integer value, integer type, internal representation, value,
167 value type, string representation
168Tcl 8.5 Tcl_IntObj(3)