home | help 
Tcl_GetNumber(3)	     Tcl Library Procedures		Tcl_GetNumber(3)

________________________________________________________________________________

NAME
     Tcl_GetNumber, Tcl_GetNumberFromObj - get numeric value from Tcl value

SYNOPSIS
     #include <tcl.h>

     #include <tclTomMath.h>

     int
     Tcl_GetNumber(interp, bytes, numBytes, clientDataPtr, typePtr)

     int
     Tcl_GetNumberFromObj(interp, objPtr, clientDataPtr, typePtr)

ARGUMENTS
     Tcl_Interp *interp (out)		    When  non-NULL, error information is
					    recorded here when the value is  not
					    in any of the numeric formats recog-
					    nized by Tcl.

     const char *bytes (in)		    Points  to	first byte of the string
					    value to be examined.

     Tcl_Size numBytes (in)		    The number	of  bytes,  starting  at
					    bytes,  that should be examined.  If
					    numBytes is negative, then all bytes
					    should be examined until  the  first
					    NUL byte terminates examination.

     void * *clientDataPtr (out)	    Points  to	space  where  a  pointer
					    value may be written through which a
					    numeric value is available to read.

     int *typePtr (out) 		    Points to space where a value may be
					    written reporting what type  of  nu-
					    meric storage is available to read.

     Tcl_Obj *objPtr (in)		    A Tcl value to be examined.
________________________________________________________________________________

DESCRIPTION
     These  procedures	enable	callers  to  retrieve a numeric value from a Tcl
     value in a numeric format recognized by Tcl.

     Tcl recognizes many values as numbers.  Several examples  include:  "0",  "
     +1",  "-2 ", " 3 ", "0xdad1", "0d09", "1_000_000", "4.0", "1e-7", "NaN", or
     "Inf".  When built-in Tcl commands act on these values as numbers, they are
     converted to a numeric representation for efficient  handling  in	C  code.
     Tcl  makes  use  of  three  C types to store these representations: double,
     Tcl_WideInt, and mp_int.  The double type is provided  by	the  C	language
     standard.	 The Tcl_WideInt type is declared in the Tcl header file, tcl.h,
     and is equivalent to the C standard type long long on most  platforms.  The
     mp_int type is declared in the header file tclTomMath.h, and implemented by
     the LibTomMath multiple-precision integer library, included with Tcl.

     The  routines Tcl_GetNumber and Tcl_GetNumberFromObj perform the same func-
     tion.  They differ only in how the arguments present the Tcl  value  to  be
     examined.	 Tcl_GetNumber	accepts  a counted string value in the arguments
     bytes and numBytes (or a NUL-terminated string value when numBytes is nega-
     tive).  Tcl_GetNumberFromObj accepts the Tcl value in objPtr.

     Both routines examine the Tcl value and determine whether Tcl recognizes it
     as a number.  If not, both routines return TCL_ERROR and  (when  interp  is
     not NULL) record an error message and error code in interp.

     If  Tcl does recognize the examined value as a number, both routines return
     TCL_OK, and use the pointer arguments clientDataPtr and typePtr (which  may
     not  be  NULL) to report information the caller can use to retrieve the nu-
     meric representation.  Both routines write to *clientDataPtr a  pointer  to
     the internal storage location where Tcl holds the converted numeric value.

     When  the converted numeric value is stored as a double, a call to math li-
     brary routine isnan determines whether that value is not  a  number  (NaN).
     If so, both Tcl_GetNumber and Tcl_GetNumberFromObj write the value TCL_NUM-
     BER_NAN  to *typePtr. If not, both routines write the value TCL_NUMBER_DOU-
     BLE to *typePtr.  These routines report  different  type  values  in  these
     cases because Tcl_GetDoubleFromObj raises an error on NaN values.	For both
     reported  type values, the storage pointer may be cast to type const double
     * and the double numeric value may be read through it.

     When the converted numeric value is stored as a Tcl_WideInt, both	Tcl_Get-
     Number and Tcl_GetNumberFromObj write the value TCL_NUMBER_INT to *typePtr.
     The  storage  pointer  may  be  cast  to  type  const Tcl_WideInt * and the
     Tcl_WideInt numeric value may be read through it.

     When the converted numeric value is stored as an mp_int, both Tcl_GetNumber
     and Tcl_GetNumberFromObj write the value TCL_NUMBER_BIG to  *typePtr.   The
     storage  pointer  may be cast to type const mp_int * and the mp_int numeric
     value may be read through it.

     Future releases of Tcl might expand or revise the recognition of values  as
     numbers.  If additional storage representations are adopted, these routines
     will  add	new  values to be written to *typePtr to identify them.  Callers
     should consider how they should react to unknown values written  to  *type-
     Ptr.

     When  callers  of	these  routines read numeric values through the reported
     storage pointer, they are accessing memory that belongs to the Tcl library.
     The Tcl library has the power to overwrite or free this memory.  The  stor-
     age  pointer  reported  by  a call to Tcl_GetNumber or Tcl_GetNumberFromObj
     should not be used after the same thread has possibly returned  control  to
     the  Tcl library.	If longer term access to the numeric value is needed, it
     should be copied into memory controlled by the caller.   Callers  must  not
     attempt to write through or free the storage pointer.

SEE ALSO
     Tcl_GetDouble, Tcl_GetDoubleFromObj, Tcl_GetWideIntFromObj

KEYWORDS
     double,  double  value,  double type, integer, integer value, integer type,
     internal representation, value, value type, string representation

Tcl				       9.0			Tcl_GetNumber(3)
home | help