1Tcl_IntObj(3)               Tcl Library Procedures               Tcl_IntObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

15       #include <tcl.h>
16
17       Tcl_Obj *
18       Tcl_NewIntObj(intValue)
19
20       Tcl_Obj *
21       Tcl_NewLongObj(longValue)
22
23       Tcl_Obj *
24       Tcl_NewWideIntObj(wideValue)
25
26       Tcl_SetIntObj(objPtr, intValue)
27
28       Tcl_SetLongObj(objPtr, longValue)
29
30       Tcl_SetWideIntObj(objPtr, wideValue)
31
32       int
33       Tcl_GetIntFromObj(interp, objPtr, intPtr)
34
35       int
36       Tcl_GetLongFromObj(interp, objPtr, longPtr)
37
38       int
39       Tcl_GetWideIntFromObj(interp, objPtr, widePtr)
40
41
42       #include <tclTomMath.h>                                                 
43
44       Tcl_Obj *                                                               │
45       Tcl_NewBignumObj(bigValue)                                              │
46
47       Tcl_SetBignumObj(objPtr, bigValue)                                      │
48
49       int                                                                     │
50       Tcl_GetBignumFromObj(interp, objPtr, bigValue)                          │
51
52       int                                                                     │
53       Tcl_TakeBignumFromObj(interp, objPtr, bigValue)                         │
54
55       int                                                                     │
56       Tcl_InitBignumFromDouble(interp, doubleValue, bigValue)                 │
57

ARGUMENTS

59       int intValue (in)                     Integer  value used to initialize
60                                             or set a Tcl object.
61
62       long longValue (in)                   Long integer value used  to  ini‐
63                                             tialize or set a Tcl object.
64
65       Tcl_WideInt wideValue (in)            Wide  integer  value used to ini‐
66                                             tialize or set a Tcl object.
67
68       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
80       Tcl_Interp *interp (in/out)           When non-NULL, an  error  message
81                                             is  left here when integral value
82                                             retrieval fails.
83
84       int *intPtr (out)                     Points  to  place  to  store  the
85                                             integer   value   retrieved  from
86                                             objPtr.
87
88       long *longPtr (out)                   Points to place to store the long
89                                             integer   value   retrieved  from
90                                             objPtr.
91
92       Tcl_WideInt *widePtr (out)            Points to place to store the wide
93                                             integer   value   retrieved  from
94                                             objPtr.
95
96       mp_int *bigValue (in/out)             Points to a multi-precision inte‐ │
97                                             ger  structure  declared  by  the │
98                                             LibTomMath library.
99
100       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
106

DESCRIPTION

108       These  procedures are used to create, modify, and read Tcl objects that │
109       hold integral values.                                                   │
110
111       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
123       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
128       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
137       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
151       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
160       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

SEE ALSO

165       Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
166

KEYWORDS

168       integer, integer object, integer type, internal representation, object,
169       object type, string representation
170
171
172
173Tcl                                   8.5                        Tcl_IntObj(3)
Impressum