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 recognized 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 numeric 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 function. 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 negative). 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 numeric 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 library routine isnan determines whether that value is not a number (NaN). If so, both Tcl_GetNumber and Tcl_GetNumberFromObj write the value TCL_NUMBER_NAN to *typePtr. If not, both routines write the value TCL_NUMBER_DOUBLE 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_GetNumber 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 *typePtr.

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 storage 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