util/X86LINUX64/man/man3/Tcl_NewLongObj.3

   1 '\"
   2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 .SH NAME
 277 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 values as integers
 278 .SH SYNOPSIS
 279 .nf
 280 \fB#include <tcl.h>\fR
 281 .sp
 282 Tcl_Obj *
 283 \fBTcl_NewIntObj\fR(\fIintValue\fR)
 284 .sp
 285 Tcl_Obj *
 286 \fBTcl_NewLongObj\fR(\fIlongValue\fR)
 287 .sp
 288 Tcl_Obj *
 289 \fBTcl_NewWideIntObj\fR(\fIwideValue\fR)
 290 .sp
 291 \fBTcl_SetIntObj\fR(\fIobjPtr, intValue\fR)
 292 .sp
 293 \fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR)
 294 .sp
 295 \fBTcl_SetWideIntObj\fR(\fIobjPtr, wideValue\fR)
 296 .sp
 297 int
 298 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
 299 .sp
 300 int
 301 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
 302 .sp
 303 int
 304 \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR)
 305 .sp
 306 .sp
 307 \fB#include <tclTomMath.h>\fR
 308 .sp
 309 Tcl_Obj *
 310 \fBTcl_NewBignumObj\fR(\fIbigValue\fR)
 311 .sp
 312 \fBTcl_SetBignumObj\fR(\fIobjPtr, bigValue\fR)
 313 .sp
 314 int
 315 \fBTcl_GetBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR)
 316 .sp
 317 int
 318 \fBTcl_TakeBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR)
 319 .sp
 320 int
 321 \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
 322 .SH ARGUMENTS
 323 .AS Tcl_WideInt doubleValue in/out
 324 .AP int intValue in
 325 Integer value used to initialize or set a Tcl value.
 326 .AP long longValue in
 327 Long integer value used to initialize or set a Tcl value.
 328 .AP Tcl_WideInt wideValue in
 329 Wide integer value used to initialize or set a Tcl value.
 330 .AP Tcl_Obj *objPtr in/out
 331 For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
 332 and \fBTcl_SetBignumObj\fR, this points to the value in which to store an
 333 integral value.  For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
 334 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
 335 \fBTcl_TakeBignumFromObj\fR, this refers to the value from which
 336 to retrieve an integral value.
 337 .AP Tcl_Interp *interp in/out
 338 When non-NULL, an error message is left here when integral value
 339 retrieval fails.
 340 .AP int *intPtr out
 341 Points to place to store the integer value retrieved from \fIobjPtr\fR.
 342 .AP long *longPtr out
 343 Points to place to store the long integer value retrieved from \fIobjPtr\fR.
 344 .AP Tcl_WideInt *widePtr out
 345 Points to place to store the wide integer value retrieved from \fIobjPtr\fR.
 346 .AP mp_int *bigValue in/out
 347 Points to a multi-precision integer structure declared by the LibTomMath
 348 library.
 349 .AP double doubleValue in
 350 Double value from which the integer part is determined and
 351 used to initialize a multi-precision integer value.
 352 .BE
 353 .SH DESCRIPTION
 354 .PP
 355 These procedures are used to create, modify, and read Tcl values
 356 that hold integral values.
 357 .PP
 358 The different routines exist to accommodate different integral types in C
 359 with which values might be exchanged.  The C integral types for which Tcl
 360 provides value exchange routines are \fBint\fR, \fBlong int\fR,
 361 \fBTcl_WideInt\fR, and \fBmp_int\fR.  The \fBint\fR and \fBlong int\fR types
 362 are provided by the C language standard.  The \fBTcl_WideInt\fR type is a
 363 typedef defined to be whatever signed integral type covers at least the
 364 64-bit integer range (-9223372036854775808 to 9223372036854775807).  Depending
 365 on the platform and the C compiler, the actual type might be
 366 \fBlong int\fR, \fBlong long int\fR, \fBint64\fR, or something else.
 367 The \fBmp_int\fR type is a multiple-precision integer type defined
 368 by the LibTomMath multiple-precision integer library.
 369 .PP
 370 The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR,
 371 and \fBTcl_NewBignumObj\fR routines each create and return a new
 372 Tcl value initialized to the integral value of the argument.  The
 373 returned Tcl value is unshared.
 374 .PP
 375 The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
 376 and \fBTcl_SetBignumObj\fR routines each set the value of an existing
 377 Tcl value pointed to by \fIobjPtr\fR to the integral value provided
 378 by the other argument.  The \fIobjPtr\fR argument must point to an
 379 unshared Tcl value.  Any attempt to set the value of a shared Tcl value
 380 violates Tcl's copy-on-write policy.  Any existing string representation
 381 or internal representation in the unshared Tcl value will be freed
 382 as a consequence of setting the new value.
 383 .PP
 384 The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
 385 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
 386 \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
 387 value of the appropriate type from the Tcl value \fIobjPtr\fR.  If the
 388 attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
 389 written to the storage provided by the caller.  The attempt might
 390 fail if \fIobjPtr\fR does not hold an integral value, or if the
 391 value exceeds the range of the target type.  If the attempt fails,
 392 then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
 393 an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
 394 of \fIobjPtr\fR may be changed to make subsequent calls to the
 395 same routine more efficient. Unlike the other functions,
 396 \fBTcl_TakeBignumFromObj\fR may set the content of the Tcl value
 397 \fIobjPtr\fR to an empty string in the process of retrieving the
 398 multiple-precision integer value.
 399 .PP
 400 The choice between \fBTcl_GetBignumFromObj\fR and
 401 \fBTcl_TakeBignumFromObj\fR is governed by how the caller will
 402 continue to use \fIobjPtr\fR.  If after the \fBmp_int\fR value
 403 is retrieved from \fIobjPtr\fR, the caller will make no more
 404 use of \fIobjPtr\fR, then using \fBTcl_TakeBignumFromObj\fR
 405 permits Tcl to detect when an unshared \fIobjPtr\fR permits the
 406 value to be moved instead of copied, which should be more efficient.
 407 If anything later in the caller requires
 408 \fIobjPtr\fR to continue to hold the same value, then
 409 \fBTcl_GetBignumFromObj\fR must be chosen.
 410 .PP
 411 The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure
 412 that extracts the integer part of \fIdoubleValue\fR and stores that
 413 integer value in the \fBmp_int\fR value \fIbigValue\fR.
 414 .SH "SEE ALSO"
 415 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 416 .SH KEYWORDS
 417 integer, integer value, integer type, internal representation, value,
 418 value type, string representation