tcl/doc/IntObj.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 '\" RCS: @(#) $Id$
   8 '\"
   9 .so man.macros
  10 .TH Tcl_IntObj 3 8.0 Tcl "Tcl Library Procedures"
  11 .BS
  12 .SH NAME
  13 Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj \- manipulate Tcl objects as integers and wide integers
  14 .SH SYNOPSIS
  15 .nf
  16 \fB#include <tcl.h>\fR
  17 .sp
  18 Tcl_Obj *
  19 \fBTcl_NewIntObj\fR(\fIintValue\fR)
  20 .sp
  21 Tcl_Obj *
  22 \fBTcl_NewLongObj\fR(\fIlongValue\fR)
  23 .sp
  24 .VS 8.4
  25 Tcl_Obj *
  26 \fBTcl_NewWideIntObj\fR(\fIwideValue\fR)
  27 .VE 8.4
  28 .sp
  29 \fBTcl_SetIntObj\fR(\fIobjPtr, intValue\fR)
  30 .sp
  31 \fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR)
  32 .sp
  33 .VS 8.4
  34 \fBTcl_SetWideIntObj\fR(\fIobjPtr, wideValue\fR)
  35 .VE 8.4
  36 .sp
  37 int
  38 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
  39 .sp
  40 int
  41 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
  42 .sp
  43 .VS 8.4
  44 int
  45 \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR)
  46 .VE 8.4
  47 .SH ARGUMENTS
  48 .AS Tcl_WideInt *interp
  49 .AP int intValue in
  50 Integer value used to initialize or set an integer object.
  51 .AP long longValue in
  52 Long integer value used to initialize or set an integer object.
  53 .AP Tcl_WideInt wideValue in
  54 .VS 8.4
  55 Wide integer value (minimum 64-bits wide where supported by the
  56 compiler) used to initialize or set a wide integer object.
  57 .VE 8.4
  58 .AP Tcl_Obj *objPtr in/out
  59 For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, and
  60 .VS 8.4
  61 \fBTcl_SetWideIntObj\fR, this points to the object to be converted to
  62 integer type.  For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
  63 and \fBTcl_GetWideIntFromObj\fR, this refers to the object from which
  64 to get an integer or long integer value; if \fIobjPtr\fR does not
  65 already point to an integer object (or a wide integer object in the
  66 case of \fBTcl_SetWideIntObj\fR and \fBTcl_GetWideIntFromObj\fR,) an
  67 .VE 8.4
  68 attempt will be made to convert it to one.
  69 .AP Tcl_Interp *interp in/out
  70 If an error occurs during conversion,
  71 an error message is left in the interpreter's result object
  72 unless \fIinterp\fR is NULL.
  73 .AP int *intPtr out
  74 Points to place to store the integer value
  75 obtained by \fBTcl_GetIntFromObj\fR from \fIobjPtr\fR.
  76 .AP long *longPtr out
  77 Points to place to store the long integer value
  78 obtained by \fBTcl_GetLongFromObj\fR from \fIobjPtr\fR.
  79 .AP Tcl_WideInt *widePtr out
  80 .VS 8.4
  81 Points to place to store the wide integer value
  82 obtained by \fBTcl_GetWideIntFromObj\fR from \fIobjPtr\fR.
  83 .VE 8.4
  84 .BE
  85
  86 .SH DESCRIPTION
  87 .PP
  88 These procedures are used to create, modify, and read
  89 integer and wide integer Tcl objects from C code.
  90 \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR,
  91 \fBTcl_SetIntObj\fR, and \fBTcl_SetLongObj\fR
  92 create a new object of integer type
  93 or modify an existing object to have integer type,
  94 .VS 8.4
  95 and \fBTcl_NewWideIntObj\fR and \fBTcl_SetWideIntObj\fR create a new
  96 object of wide integer type or modify an existing object to have wide
  97 integer type.
  98 .VE 8.4
  99 \fBTcl_NewIntObj\fR and \fBTcl_SetIntObj\fR set the object to have the
 100 integer value given by \fIintValue\fR,
 101 \fBTcl_NewLongObj\fR and \fBTcl_SetLongObj\fR
 102 set the object to have the
 103 long integer value given by \fIlongValue\fR,
 104 .VS 8.4
 105 and \fBTcl_NewWideIntObj\fR and \fBTcl_SetWideIntObj\fR set the object
 106 to have the wide integer value given by \fIwideValue\fR.
 107 \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR and \fBTcl_NewWideIntObj\fR
 108 return a pointer to a newly created object with reference count zero.
 109 These procedures set the object's type to be integer
 110 and assign the integer value to the object's internal representation
 111 \fIlongValue\fR or \fIwideValue\fR member (as appropriate).
 112 \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR
 113 and \fBTcl_SetWideIntObj\fR
 114 .VE 8.4
 115 invalidate any old string representation and,
 116 if the object is not already an integer object,
 117 free any old internal representation.
 118 .PP
 119 \fBTcl_GetIntFromObj\fR and \fBTcl_GetLongFromObj\fR
 120 attempt to return an integer value from the Tcl object \fIobjPtr\fR,
 121 .VS 8.4
 122 and \fBTcl_GetWideIntFromObj\fR attempts to return a wide integer
 123 value from the Tcl object \fIobjPtr\fR.
 124 If the object is not already an integer object,
 125 or a wide integer object in the case of \fBTcl_GetWideIntFromObj\fR
 126 .VE 8.4
 127 they will attempt to convert it to one.
 128 If an error occurs during conversion, they return \fBTCL_ERROR\fR
 129 and leave an error message in the interpreter's result object
 130 unless \fIinterp\fR is NULL.
 131 Also, if the long integer held in the object's internal representation
 132 \fIlongValue\fR member can not be represented in a (non-long) integer,
 133 \fBTcl_GetIntFromObj\fR returns \fBTCL_ERROR\fR
 134 and leaves an error message in the interpreter's result object
 135 unless \fIinterp\fR is NULL.
 136 Otherwise, all three procedures return \fBTCL_OK\fR and
 137 store the integer, long integer value
 138 .VS 8.4
 139 or wide integer in the address given by \fIintPtr\fR, \fIlongPtr\fR
 140 and \fIwidePtr\fR
 141 .VE 8.4
 142 respectively.  If the object is not already an integer or wide integer
 143 object, the conversion will free any old internal representation.
 144
 145 .SH "SEE ALSO"
 146 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
 147
 148 .SH KEYWORDS
 149 integer, integer object, integer type, internal representation, object, object type, string representation