diff options
Diffstat (limited to 'doc/DoubleObj.3')
| -rw-r--r-- | doc/DoubleObj.3 | 65 |
1 files changed, 26 insertions, 39 deletions
diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3 index b65af58..12818b0 100644 --- a/doc/DoubleObj.3 +++ b/doc/DoubleObj.3 @@ -23,55 +23,42 @@ int .SH ARGUMENTS .AS Tcl_Interp doubleValue in/out .AP double doubleValue in -A double-precision floating point value used to initialize or set a double object. +A double-precision floating-point value used to initialize or set a Tcl object. .AP Tcl_Obj *objPtr in/out -For \fBTcl_SetDoubleObj\fR, this points to the object to be converted -to double type. +For \fBTcl_SetDoubleObj\fR, this points to the object in which to store a +double value. For \fBTcl_GetDoubleFromObj\fR, this refers to the object -from which to get a double value; -if \fIobjPtr\fR does not already point to a double object, -an attempt will be made to convert it to one. +from which to retrieve a double value. .AP Tcl_Interp *interp in/out -If an error occurs during conversion, -an error message is left in the interpreter's result object -unless \fIinterp\fR is NULL. +When non-NULL, an error message is left here when double value retrieval fails. .AP double *doublePtr out -Points to place to store the double value -obtained from \fIobjPtr\fR. +Points to place to store the double value obtained from \fIobjPtr\fR. .BE .SH DESCRIPTION .PP -These procedures are used to create, modify, and read -double Tcl objects from C code. -\fBTcl_NewDoubleObj\fR and \fBTcl_SetDoubleObj\fR -will create a new object of double type -or modify an existing object to have double type. -Both of these procedures set the object to have the -double-precision floating point value given by \fIdoubleValue\fR; -\fBTcl_NewDoubleObj\fR returns a pointer to a newly created object -with reference count zero. -Both procedures set the object's type to be double -and assign the double value to the object's internal representation -\fIdoubleValue\fR member. -\fBTcl_SetDoubleObj\fR invalidates any old string representation -and, if the object is not already a double object, -frees any old internal representation. +These procedures are used to create, modify, and read Tcl objects that +hold double-precision floating-point values. .PP -\fBTcl_GetDoubleFromObj\fR attempts to return a double value -from the Tcl object \fIobjPtr\fR. -If the object is not already a double object, -it will attempt to convert it to one. -If an error occurs during conversion, it returns \fBTCL_ERROR\fR -and leaves an error message in the interpreter's result object -unless \fIinterp\fR is NULL. -Otherwise, it returns \fBTCL_OK\fR and stores the double value -in the address given by \fIdoublePtr\fR. -If the object is not already a double object, -the conversion will free any old internal representation. - +\fBTcl_NewDoubleObj\fR creates and returns a new Tcl object initialized to +the double value \fIdoubleValue\fR. The returned Tcl object is unshared. +.PP +\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl object pointed to +by \fIobjPtr\fR to the double value \fIdoubleValue\fR. The \fIobjPtr\fR +argument must point to an 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 object +will be freed as a consequence of setting the new value. +.PP +\fBTcl_GetDoubleFromObj\fR attempts to retrieve a double value from the +Tcl object \fIobjPtr\fR. If the attempt succeeds, then \fBTCL_OK\fR is +returned, and the double value is written to the storage pointed to by +\fIdoublePtr\fR. 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 \fBTcl_GetDoubleFromObj\fR more efficient. +'\" TODO: add discussion of treatment of NaN value .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult - .SH KEYWORDS double, double object, double type, internal representation, object, object type, string representation |