diff options
Diffstat (limited to 'doc/DoubleObj.3')
| -rw-r--r-- | doc/DoubleObj.3 | 75 |
1 files changed, 30 insertions, 45 deletions
diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3 index 4af284d..4b422d4 100644 --- a/doc/DoubleObj.3 +++ b/doc/DoubleObj.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: DoubleObj.3,v 1.3 2004/09/06 09:44:56 dkf Exp $ -'\" -.so man.macros .TH Tcl_DoubleObj 3 8.0 Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME -Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl objects as floating-point values +Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl values as floating-point values .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -25,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 value. .AP Tcl_Obj *objPtr in/out -For \fBTcl_SetDoubleObj\fR, this points to the object to be converted -to double type. -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. +For \fBTcl_SetDoubleObj\fR, this points to the value in which to store a +double value. +For \fBTcl_GetDoubleFromObj\fR, this refers to the value +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 values 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 value initialized to +the double value \fIdoubleValue\fR. The returned Tcl value is unshared. +.PP +\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl value pointed to +by \fIobjPtr\fR to the double value \fIdoubleValue\fR. The \fIobjPtr\fR +argument must point to an unshared Tcl value. Any attempt to set the value +of a shared Tcl value violates Tcl's copy-on-write policy. Any existing +string representation or internal representation in the unshared Tcl value +will be freed as a consequence of setting the new value. +.PP +\fBTcl_GetDoubleFromObj\fR attempts to retrieve a double value from the +Tcl value \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 +double, double value, double type, internal representation, value, value type, string representation |