diff options
Diffstat (limited to 'doc/IntObj.3')
| -rw-r--r-- | doc/IntObj.3 | 89 |
1 files changed, 28 insertions, 61 deletions
diff --git a/doc/IntObj.3 b/doc/IntObj.3 index 18d867e..e228bdb 100644 --- a/doc/IntObj.3 +++ b/doc/IntObj.3 @@ -3,12 +3,12 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME -Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_GetWideUIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers +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 objects as integer values .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -32,18 +32,13 @@ int \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR) .sp int -\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR) -.sp -int \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR) .sp int \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR) .sp -int -\fBTcl_GetWideUIntFromObj\fR(\fIinterp, objPtr, uwidePtr\fR) -.sp .sp +.VS 8.5 \fB#include <tclTomMath.h>\fR .sp Tcl_Obj * @@ -59,22 +54,21 @@ int .sp int \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR) +.VE 8.5 .SH ARGUMENTS .AS Tcl_WideInt doubleValue in/out -.AP int endValue in -\fBTcl_GetIntForIndex\fR will return this when the input value is "end". .AP int intValue in -Integer value used to initialize or set a Tcl value. +Integer value used to initialize or set a Tcl object. .AP long longValue in -Long integer value used to initialize or set a Tcl value. +Long integer value used to initialize or set a Tcl object. .AP Tcl_WideInt wideValue in -Wide integer value used to initialize or set a Tcl value. +Wide integer value used to initialize or set a Tcl object. .AP Tcl_Obj *objPtr in/out For \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, -and \fBTcl_SetBignumObj\fR, this points to the value in which to store an +and \fBTcl_SetBignumObj\fR, this points to the object in which to store an integral value. For \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR, \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and -\fBTcl_TakeBignumFromObj\fR, this refers to the value from which +\fBTcl_TakeBignumFromObj\fR, this refers to the object from which to retrieve an integral value. .AP Tcl_Interp *interp in/out When non-NULL, an error message is left here when integral value @@ -85,19 +79,23 @@ Points to place to store the integer value retrieved from \fIobjPtr\fR. Points to place to store the long integer value retrieved from \fIobjPtr\fR. .AP Tcl_WideInt *widePtr out Points to place to store the wide integer value retrieved from \fIobjPtr\fR. -.AP Tcl_WideUInt *uwidePtr out -Points to place to store the unsigned wide integer value retrieved from \fIobjPtr\fR. .AP mp_int *bigValue in/out +.VS 8.5 Points to a multi-precision integer structure declared by the LibTomMath library. +.VE 8.5 .AP double doubleValue in +.VS 8.5 Double value from which the integer part is determined and used to initialize a multi-precision integer value. +.VE 8.5 .BE + .SH DESCRIPTION .PP -These procedures are used to create, modify, and read Tcl values -that hold integral values. +.VS 8.5 +These procedures are used to create, modify, and read Tcl objects +that hold integral values. .PP The different routines exist to accommodate different integral types in C with which values might be exchanged. The C integral types for which Tcl @@ -107,38 +105,28 @@ are provided by the C language standard. The \fBTcl_WideInt\fR type is a typedef defined to be whatever signed integral type covers at least the 64-bit integer range (-9223372036854775808 to 9223372036854775807). Depending on the platform and the C compiler, the actual type might be -\fBlong long int\fR, or something else. +\fBlong int\fR, \fBlong long int\fR, \fBint64\fR, or something else. The \fBmp_int\fR type is a multiple-precision integer type defined -by the LibTomMath multiple-precision integer library. +by the LibTomMath multiple-precision integer library. .PP The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR, and \fBTcl_NewBignumObj\fR routines each create and return a new -Tcl value initialized to the integral value of the argument. The -returned Tcl value is unshared. +Tcl object initialized to the integral value of the argument. The +returned Tcl object is unshared. .PP The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, and \fBTcl_SetBignumObj\fR routines each set the value of an existing -Tcl value pointed to by \fIobjPtr\fR to the integral value provided +Tcl object pointed to by \fIobjPtr\fR to the integral value provided by the other argument. The \fIobjPtr\fR argument must point to an -unshared Tcl value. Any attempt to set the value of a shared Tcl value +unshared Tcl object. Any attempt to set the value of a shared Tcl object violates Tcl's copy-on-write policy. Any existing string representation -or internal representation in the unshared Tcl value will be freed +or internal representation in the unshared Tcl object will be freed as a consequence of setting the new value. .PP -The \fBTcl_GetIntForIndex\fR routine attempts to retrieve an index -value from the Tcl value \fIobjPtr\fR. If the attempt succeeds, -then \fBTCL_OK\fR is returned, and the value is written to the -storage provided by the caller. The attempt might fail if -\fIobjPtr\fR does not hold an index value. If the attempt fails, -then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL, -an error message is left in \fIinterp\fR. The \fBTcl_ObjType\fR -of \fIobjPtr\fR may be changed to make subsequent calls to the -same routine more efficient. -.PP The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR, \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral -value of the appropriate type from the Tcl value \fIobjPtr\fR. If the +value of the appropriate type from the Tcl object \fIobjPtr\fR. If the attempt succeeds, then \fBTCL_OK\fR is returned, and the value is written to the storage provided by the caller. The attempt might fail if \fIobjPtr\fR does not hold an integral value, or if the @@ -147,7 +135,7 @@ then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR. The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent calls to the same routine more efficient. Unlike the other functions, -\fBTcl_TakeBignumFromObj\fR may set the content of the Tcl value +\fBTcl_TakeBignumFromObj\fR may set the content of the Tcl object \fIobjPtr\fR to an empty string in the process of retrieving the multiple-precision integer value. .PP @@ -165,29 +153,8 @@ If anything later in the caller requires The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure that extracts the integer part of \fIdoubleValue\fR and stores that integer value in the \fBmp_int\fR value \fIbigValue\fR. -.SH "REFERENCE COUNT MANAGEMENT" -.PP -\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR, and -\fBTcl_NewBignumObj\fR always return a zero-reference object, much like -\fBTcl_NewObj\fR. -.PP -\fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, and -\fBTcl_SetBignumObj\fR do not modify the reference count of their \fIobjPtr\fR -arguments, but do require that the object be unshared. -.PP -\fBTcl_GetIntFromObj\fR, \fBTcl_GetIntForIndex\fR, \fBTcl_GetLongFromObj\fR, -\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and -\fBTcl_TakeBignumFromObj\fR do not modify the reference count of their -\fIobjPtr\fR arguments; they only read. Note however that this function may -set the interpreter result; if that is the only place that is holding a -reference to the object, it will be deleted. Also note that if -\fBTcl_TakeBignumFromObj\fR is given an unshared value, the value of that -object may be modified; it is intended to be used when the value is -.QW consumed -by the operation at this point. - +.VE 8.5 .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult .SH KEYWORDS -integer, integer value, integer type, internal representation, value, -value type, string representation +integer, integer object, integer type, internal representation, object, object type, string representation |