util/src/TclTk/tcl8.6.12/doc/DoubleObj.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_DoubleObj 3 8.0 Tcl "Tcl Library Procedures"
   8 .so man.macros
   9 .BS
  10 .SH NAME
  11 Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl values as floating-point values
  12 .SH SYNOPSIS
  13 .nf
  14 \fB#include <tcl.h>\fR
  15 .sp
  16 Tcl_Obj *
  17 \fBTcl_NewDoubleObj\fR(\fIdoubleValue\fR)
  18 .sp
  19 \fBTcl_SetDoubleObj\fR(\fIobjPtr, doubleValue\fR)
  20 .sp
  21 int
  22 \fBTcl_GetDoubleFromObj\fR(\fIinterp, objPtr, doublePtr\fR)
  23 .SH ARGUMENTS
  24 .AS Tcl_Interp doubleValue in/out
  25 .AP double doubleValue in
  26 A double-precision floating-point value used to initialize or set a Tcl value.
  27 .AP Tcl_Obj *objPtr in/out
  28 For \fBTcl_SetDoubleObj\fR, this points to the value in which to store a
  29 double value.
  30 For \fBTcl_GetDoubleFromObj\fR, this refers to the value
  31 from which to retrieve a double value.
  32 .AP Tcl_Interp *interp in/out
  33 When non-NULL, an error message is left here when double value retrieval fails.
  34 .AP double *doublePtr out
  35 Points to place to store the double value obtained from \fIobjPtr\fR.
  36 .BE
  37
  38 .SH DESCRIPTION
  39 .PP
  40 These procedures are used to create, modify, and read Tcl values that
  41 hold double-precision floating-point values.
  42 .PP
  43 \fBTcl_NewDoubleObj\fR creates and returns a new Tcl value initialized to
  44 the double value \fIdoubleValue\fR.  The returned Tcl value is unshared.
  45 .PP
  46 \fBTcl_SetDoubleObj\fR sets the value of an existing Tcl value pointed to
  47 by \fIobjPtr\fR to the double value \fIdoubleValue\fR.  The \fIobjPtr\fR
  48 argument must point to an unshared Tcl value.  Any attempt to set the value
  49 of a shared Tcl value violates Tcl's copy-on-write policy.  Any existing
  50 string representation or internal representation in the unshared Tcl value
  51 will be freed as a consequence of setting the new value.
  52 .PP
  53 \fBTcl_GetDoubleFromObj\fR attempts to retrieve a double value from the
  54 Tcl value \fIobjPtr\fR.  If the attempt succeeds, then \fBTCL_OK\fR is
  55 returned, and the double value is written to the storage pointed to by
  56 \fIdoublePtr\fR.  If the attempt fails, then \fBTCL_ERROR\fR is returned,
  57 and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR.
  58 The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent
  59 calls to \fBTcl_GetDoubleFromObj\fR more efficient.
  60 '\" TODO: add discussion of treatment of NaN value
  61 .SH "SEE ALSO"
  62 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
  63 .SH KEYWORDS
  64 double, double value, double type, internal representation, value, value type, string representation