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 values  as
12       integers
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 value.
61
62       long longValue (in)                   Long integer value used  to  ini‐
63                                             tialize or set a Tcl value.
64
65       Tcl_WideInt wideValue (in)            Wide  integer  value used to ini‐
66                                             tialize or set a Tcl value.
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  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
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

DESCRIPTION

107       These  procedures  are used to create, modify, and read Tcl values that
108       hold integral values.
109
110       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
122       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
126       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
135       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
149       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
158       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

SEE ALSO

163       Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
164

KEYWORDS

166       integer, integer value, integer type, internal  representation,  value,
167       value type, string representation
168
169
170
171Tcl                                   8.5                        Tcl_IntObj(3)
Impressum