From 260c5156ed0ec2b944268320a267cee9a57cd547 Mon Sep 17 00:00:00 2001
From: dgp <dgp@users.sourceforge.net>
Date: Sun, 18 Sep 2022 13:59:26 +0000
Subject: TIP implementation to add/use public routines Tcl_GetNumber(FromObj).

---
 generic/tcl.decls     |  8 ++++++++
 generic/tcl.h         | 14 ++++++++++++++
 generic/tclBasic.c    | 32 ++++++++++++++++----------------
 generic/tclDecls.h    | 14 ++++++++++++++
 generic/tclExecute.c  |  4 ++--
 generic/tclInt.h      | 18 ------------------
 generic/tclLink.c     |  2 +-
 generic/tclObj.c      | 40 ++++++++++++++++++++++++++++++++++++++--
 generic/tclStubInit.c |  2 ++
 generic/tclUtil.c     | 10 +++++-----
 10 files changed, 100 insertions(+), 44 deletions(-)

diff --git a/generic/tcl.decls b/generic/tcl.decls
index d08ba0a..2bbad1c 100644
--- a/generic/tcl.decls
+++ b/generic/tcl.decls
@@ -2523,6 +2523,14 @@ declare 679 {
     int Tcl_NRCallObjProc2(Tcl_Interp *interp, Tcl_ObjCmdProc2 *objProc2,
 	    void *clientData, size_t objc, Tcl_Obj *const objv[])
 }
+declare 680 {
+    int Tcl_GetNumberFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr,
+	    void **clientDataPtr, int *typePtr)
+}
+declare 681 {
+    int Tcl_GetNumber(Tcl_Interp *interp, const char *bytes, size_t numBytes,
+	    void **clientDataPtr, int *typePtr)
+}
 
 # ----- BASELINE -- FOR -- 8.7.0 ----- #
 
diff --git a/generic/tcl.h b/generic/tcl.h
index f17d43e..cd16ea9 100644
--- a/generic/tcl.h
+++ b/generic/tcl.h
@@ -974,6 +974,20 @@ typedef struct Tcl_DString {
 #define TCL_INTEGER_SPACE	(3*(int)sizeof(Tcl_WideInt))
 
 /*
+ *----------------------------------------------------------------------------
+ * Type values returned by Tcl_GetNumberFromObj
+ *	TCL_NUMBER_INT		Representation is a Tcl_WideInt
+ *	TCL_NUMBER_BIG		Representation is an mp_int
+ *	TCL_NUMBER_DOUBLE	Representation is a double
+ *	TCL_NUMBER_NAN		Value is NaN.
+ */
+
+#define TCL_NUMBER_INT          2
+#define TCL_NUMBER_BIG          3
+#define TCL_NUMBER_DOUBLE       4
+#define TCL_NUMBER_NAN          5
+
+/*
  * Flag values passed to Tcl_ConvertElement.
  * TCL_DONT_USE_BRACES forces it not to enclose the element in braces, but to
  *	use backslash quoting instead.
diff --git a/generic/tclBasic.c b/generic/tclBasic.c
index b806c33..d7afc14 100644
--- a/generic/tclBasic.c
+++ b/generic/tclBasic.c
@@ -4133,7 +4133,7 @@ OldMathFuncProc(
 
     args = (Tcl_Value *)ckalloc(dataPtr->numArgs * sizeof(Tcl_Value));
     for (j = 1, k = 0; j < objc; ++j, ++k) {
-	/* TODO: Convert to TclGetNumberFromObj? */
+	/* TODO: Convert to Tcl_GetNumberFromObj? */
 	valuePtr = objv[j];
 	result = Tcl_GetDoubleFromObj(NULL, valuePtr, &d);
 #ifdef ACCEPT_NAN
@@ -7041,7 +7041,7 @@ Tcl_ExprLongObj(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, resultPtr, &internalPtr, &type)!=TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, resultPtr, &internalPtr, &type)!=TCL_OK) {
 	return TCL_ERROR;
     }
 
@@ -7087,7 +7087,7 @@ Tcl_ExprDoubleObj(
 	return TCL_ERROR;
     }
 
-    result = TclGetNumberFromObj(interp, resultPtr, &internalPtr, &type);
+    result = Tcl_GetNumberFromObj(interp, resultPtr, &internalPtr, &type);
     if (result == TCL_OK) {
 	switch (type) {
 	case TCL_NUMBER_NAN:
@@ -7808,7 +7808,7 @@ ExprIsqrtFunc(
      * Make sure that the arg is a number.
      */
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
 	return TCL_ERROR;
     }
 
@@ -8071,7 +8071,7 @@ ExprAbsFunc(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
 	return TCL_ERROR;
     }
 
@@ -8226,7 +8226,7 @@ ExprIntFunc(
 	MathFuncWrongNumArgs(interp, 2, objc, objv);
 	return TCL_ERROR;
     }
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
 	return TCL_ERROR;
     }
 
@@ -8307,7 +8307,7 @@ ExprMaxMinFunc(
     }
     res = objv[1];
     for (i = 1; i < objc; i++) {
-        if (TclGetNumberFromObj(interp, objv[i], &ptr, &type) != TCL_OK) {
+        if (Tcl_GetNumberFromObj(interp, objv[i], &ptr, &type) != TCL_OK) {
             return TCL_ERROR;
         }
         if (type == TCL_NUMBER_NAN) {
@@ -8459,7 +8459,7 @@ ExprRoundFunc(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
 	return TCL_ERROR;
     }
 
@@ -8727,7 +8727,7 @@ ExprIsFiniteFunc(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
         return TCL_ERROR;
     }
     if (type != TCL_NUMBER_NAN) {
@@ -8758,7 +8758,7 @@ ExprIsInfinityFunc(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
         return TCL_ERROR;
     }
     if (type != TCL_NUMBER_NAN) {
@@ -8788,7 +8788,7 @@ ExprIsNaNFunc(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
         return TCL_ERROR;
     }
     if (type != TCL_NUMBER_NAN) {
@@ -8818,7 +8818,7 @@ ExprIsNormalFunc(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
         return TCL_ERROR;
     }
     if (type != TCL_NUMBER_NAN) {
@@ -8848,7 +8848,7 @@ ExprIsSubnormalFunc(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
         return TCL_ERROR;
     }
     if (type != TCL_NUMBER_NAN) {
@@ -8878,7 +8878,7 @@ ExprIsUnorderedFunc(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
         return TCL_ERROR;
     }
     if (type == TCL_NUMBER_NAN) {
@@ -8888,7 +8888,7 @@ ExprIsUnorderedFunc(
         result = (ClassifyDouble(d) == FP_NAN);
     }
 
-    if (TclGetNumberFromObj(interp, objv[2], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[2], &ptr, &type) != TCL_OK) {
         return TCL_ERROR;
     }
     if (type == TCL_NUMBER_NAN) {
@@ -8920,7 +8920,7 @@ FloatClassifyObjCmd(
 	return TCL_ERROR;
     }
 
-    if (TclGetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
+    if (Tcl_GetNumberFromObj(interp, objv[1], &ptr, &type) != TCL_OK) {
         return TCL_ERROR;
     }
     if (type == TCL_NUMBER_NAN) {
diff --git a/generic/tclDecls.h b/generic/tclDecls.h
index 3917d0f..82d592b 100644
--- a/generic/tclDecls.h
+++ b/generic/tclDecls.h
@@ -1996,6 +1996,14 @@ EXTERN Tcl_Command	Tcl_NRCreateCommand2(Tcl_Interp *interp,
 EXTERN int		Tcl_NRCallObjProc2(Tcl_Interp *interp,
 				Tcl_ObjCmdProc2 *objProc2, void *clientData,
 				size_t objc, Tcl_Obj *const objv[]);
+/* 680 */
+EXTERN int		Tcl_GetNumberFromObj(Tcl_Interp *interp,
+				Tcl_Obj *objPtr, void **clientDataPtr,
+				int *typePtr);
+/* 681 */
+EXTERN int		Tcl_GetNumber(Tcl_Interp *interp, const char *bytes,
+				size_t numBytes, void **clientDataPtr,
+				int *typePtr);
 
 typedef struct {
     const struct TclPlatStubs *tclPlatStubs;
@@ -2711,6 +2719,8 @@ typedef struct TclStubs {
     Tcl_Trace (*tcl_CreateObjTrace2) (Tcl_Interp *interp, int level, int flags, Tcl_CmdObjTraceProc2 *objProc2, void *clientData, Tcl_CmdObjTraceDeleteProc *delProc); /* 677 */
     Tcl_Command (*tcl_NRCreateCommand2) (Tcl_Interp *interp, const char *cmdName, Tcl_ObjCmdProc2 *proc, Tcl_ObjCmdProc2 *nreProc2, void *clientData, Tcl_CmdDeleteProc *deleteProc); /* 678 */
     int (*tcl_NRCallObjProc2) (Tcl_Interp *interp, Tcl_ObjCmdProc2 *objProc2, void *clientData, size_t objc, Tcl_Obj *const objv[]); /* 679 */
+    int (*tcl_GetNumberFromObj) (Tcl_Interp *interp, Tcl_Obj *objPtr, void **clientDataPtr, int *typePtr); /* 680 */
+    int (*tcl_GetNumber) (Tcl_Interp *interp, const char *bytes, size_t numBytes, void **clientDataPtr, int *typePtr); /* 681 */
 } TclStubs;
 
 extern const TclStubs *tclStubsPtr;
@@ -4099,6 +4109,10 @@ extern const TclStubs *tclStubsPtr;
 	(tclStubsPtr->tcl_NRCreateCommand2) /* 678 */
 #define Tcl_NRCallObjProc2 \
 	(tclStubsPtr->tcl_NRCallObjProc2) /* 679 */
+#define Tcl_GetNumberFromObj \
+	(tclStubsPtr->tcl_GetNumberFromObj) /* 680 */
+#define Tcl_GetNumber \
+	(tclStubsPtr->tcl_GetNumber) /* 681 */
 
 #endif /* defined(USE_TCL_STUBS) */
 
diff --git a/generic/tclExecute.c b/generic/tclExecute.c
index 8aa3bb2..dc5adc2 100644
--- a/generic/tclExecute.c
+++ b/generic/tclExecute.c
@@ -502,7 +502,7 @@ VarHashCreateVar(
 
 /*
  * Macro used in this file to save a function call for common uses of
- * TclGetNumberFromObj(). The ANSI C "prototype" is:
+ * Tcl_GetNumberFromObj(). The ANSI C "prototype" is:
  *
  * MODULE_SCOPE int GetNumberFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr,
  *			void **ptrPtr, int *tPtr);
@@ -521,7 +521,7 @@ VarHashCreateVar(
 		    (&((objPtr)->internalRep.doubleValue)), TCL_OK) :	\
     (((objPtr)->bytes != NULL) && ((objPtr)->length == 0))		\
 	? TCL_ERROR :			\
-    TclGetNumberFromObj((interp), (objPtr), (ptrPtr), (tPtr)))
+    Tcl_GetNumberFromObj((interp), (objPtr), (ptrPtr), (tPtr)))
 
 /*
  * Macro used to make the check for type overflow more mnemonic. This works by
diff --git a/generic/tclInt.h b/generic/tclInt.h
index 09f22d3..9eba8c5 100644
--- a/generic/tclInt.h
+++ b/generic/tclInt.h
@@ -2875,21 +2875,6 @@ typedef struct ProcessGlobalValue {
 				/* Reject underscore digit separator */
 
 /*
- *----------------------------------------------------------------------
- * Type values TclGetNumberFromObj
- *----------------------------------------------------------------------
- */
-
-#define TCL_NUMBER_INT		2
-#if !defined(TCL_NO_DEPRECATED)
-#   define TCL_NUMBER_LONG		1 /* deprecated, not used any more */
-#   define TCL_NUMBER_WIDE		TCL_NUMBER_INT /* deprecated */
-#endif
-#define TCL_NUMBER_BIG		3
-#define TCL_NUMBER_DOUBLE	4
-#define TCL_NUMBER_NAN		5
-
-/*
  *----------------------------------------------------------------
  * Variables shared among Tcl modules but not used by the outside world.
  *----------------------------------------------------------------
@@ -3199,9 +3184,6 @@ MODULE_SCOPE int	TclGetCompletionCodeFromObj(Tcl_Interp *interp,
 			    Tcl_Obj *value, int *code);
 MODULE_SCOPE Proc *	TclGetLambdaFromObj(Tcl_Interp *interp,
 			    Tcl_Obj *objPtr, Tcl_Obj **nsObjPtrPtr);
-MODULE_SCOPE int	TclGetNumberFromObj(Tcl_Interp *interp,
-			    Tcl_Obj *objPtr, void **clientDataPtr,
-			    int *typePtr);
 MODULE_SCOPE int	TclGetOpenModeEx(Tcl_Interp *interp,
 			    const char *modeString, int *seekFlagPtr,
 			    int *binaryPtr);
diff --git a/generic/tclLink.c b/generic/tclLink.c
index 6bd65fa..0d57d44 100644
--- a/generic/tclLink.c
+++ b/generic/tclLink.c
@@ -530,7 +530,7 @@ GetUWide(
     void *clientData;
     int type, intValue;
 
-    if (TclGetNumberFromObj(NULL, objPtr, &clientData, &type) == TCL_OK) {
+    if (Tcl_GetNumberFromObj(NULL, objPtr, &clientData, &type) == TCL_OK) {
 	if (type == TCL_NUMBER_INT) {
 	    *widePtr = *((const Tcl_WideInt *) clientData);
 	    return (*widePtr < 0);
diff --git a/generic/tclObj.c b/generic/tclObj.c
index 5726596..f9b5bd3 100644
--- a/generic/tclObj.c
+++ b/generic/tclObj.c
@@ -3856,7 +3856,7 @@ TclSetBignumInternalRep(
 /*
  *----------------------------------------------------------------------
  *
- * TclGetNumberFromObj --
+ * Tcl_GetNumberFromObj --
  *
  *      Extracts a number (of any possible numeric type) from an object.
  *
@@ -3874,7 +3874,7 @@ TclSetBignumInternalRep(
  */
 
 int
-TclGetNumberFromObj(
+Tcl_GetNumberFromObj(
     Tcl_Interp *interp,
     Tcl_Obj *objPtr,
     ClientData *clientDataPtr,
@@ -3909,6 +3909,42 @@ TclGetNumberFromObj(
 	    TclParseNumber(interp, objPtr, "number", NULL, -1, NULL, 0));
     return TCL_ERROR;
 }
+
+int
+Tcl_GetNumber(
+    Tcl_Interp *interp,
+    const char *bytes,
+    size_t numBytes,
+    ClientData *clientDataPtr,
+    int *typePtr)
+{
+    static Tcl_ThreadDataKey numberCacheKey;
+    Tcl_Obj *objPtr = (Tcl_Obj *)Tcl_GetThreadData(&numberCacheKey,
+	    sizeof(Tcl_Obj));
+
+    Tcl_FreeInternalRep(objPtr);
+
+    if (bytes == NULL) {
+	bytes = &tclEmptyString;
+	numBytes = 0;
+    }
+    if (numBytes == (size_t)TCL_INDEX_NONE) {
+	numBytes = strlen(bytes);
+    }
+    if (numBytes > INT_MAX) {
+	if (interp) {
+            Tcl_SetObjResult(interp, Tcl_ObjPrintf(
+                    "max size for a Tcl value (%d bytes) exceeded", INT_MAX));
+	    Tcl_SetErrorCode(interp, "TCL", "MEMORY", NULL);
+	}
+	return TCL_ERROR;
+    }
+
+    objPtr->bytes = (char *) bytes;
+    objPtr->length = numBytes;
+
+    return Tcl_GetNumberFromObj(interp, objPtr, clientDataPtr, typePtr);
+}
 
 /*
  *----------------------------------------------------------------------
diff --git a/generic/tclStubInit.c b/generic/tclStubInit.c
index ae00b04..4e6041e 100644
--- a/generic/tclStubInit.c
+++ b/generic/tclStubInit.c
@@ -2043,6 +2043,8 @@ const TclStubs tclStubs = {
     Tcl_CreateObjTrace2, /* 677 */
     Tcl_NRCreateCommand2, /* 678 */
     Tcl_NRCallObjProc2, /* 679 */
+    Tcl_GetNumberFromObj, /* 680 */
+    Tcl_GetNumber, /* 681 */
 };
 
 /* !END!: Do not edit above this line. */
diff --git a/generic/tclUtil.c b/generic/tclUtil.c
index 7ab6eae..742bded 100644
--- a/generic/tclUtil.c
+++ b/generic/tclUtil.c
@@ -3644,7 +3644,7 @@ GetWideForIndex(
 {
     int numType;
     ClientData cd;
-    int code = TclGetNumberFromObj(NULL, objPtr, &cd, &numType);
+    int code = Tcl_GetNumberFromObj(NULL, objPtr, &cd, &numType);
 
     if (code == TCL_OK) {
 	if (numType == TCL_NUMBER_INT) {
@@ -3803,7 +3803,7 @@ GetEndOffsetFromObj(
 		    /* ... value continues with [-+] ... */
 
 		    /* Save first integer as wide if possible */
-		    TclGetNumberFromObj(NULL, objPtr, &cd, &t1);
+		    Tcl_GetNumberFromObj(NULL, objPtr, &cd, &t1);
 		    if (t1 == TCL_NUMBER_INT) {
 			w1 = (*(Tcl_WideInt *)cd);
 		    }
@@ -3813,7 +3813,7 @@ GetEndOffsetFromObj(
 			/* ... value concludes with second valid integer */
 
 			/* Save second integer as wide if possible */
-			TclGetNumberFromObj(NULL, objPtr, &cd, &t2);
+			Tcl_GetNumberFromObj(NULL, objPtr, &cd, &t2);
 			if (t2 == TCL_NUMBER_INT) {
 			    w2 = (*(Tcl_WideInt *)cd);
 			}
@@ -3866,7 +3866,7 @@ GetEndOffsetFromObj(
 			    Tcl_ExprObj(compute, objPtr, &sum);
 			    Tcl_DeleteInterp(compute);
 			}
-			TclGetNumberFromObj(NULL, sum, &cd, &numType);
+			Tcl_GetNumberFromObj(NULL, sum, &cd, &numType);
 
 			if (numType == TCL_NUMBER_INT) {
 			    /* sum holds an integer in the signed wide range */
@@ -3917,7 +3917,7 @@ GetEndOffsetFromObj(
 	    }
 
 	    /* Got an integer offset; pull it from where parser left it. */
-	    TclGetNumberFromObj(NULL, objPtr, &cd, &t);
+	    Tcl_GetNumberFromObj(NULL, objPtr, &cd, &t);
 
 	    if (t == TCL_NUMBER_BIG) {
 		/* Truncate to the signed wide range. */
-- 
cgit v0.12


From 414f4c9f7c689e4c1cba2c4f568db0ff3b5df688 Mon Sep 17 00:00:00 2001
From: dgp <dgp@users.sourceforge.net>
Date: Wed, 28 Sep 2022 18:41:42 +0000
Subject: WIP on documentation of proposed routines.

---
 doc/Number.3 | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 doc/Number.3

diff --git a/doc/Number.3 b/doc/Number.3
new file mode 100644
index 0000000..588171e
--- /dev/null
+++ b/doc/Number.3
@@ -0,0 +1,88 @@
+'\"
+'\" Contribution from Don Porter, NIST, 2022. (not subject to US copyright)
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH Tcl_GetNumber 3 8.7 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tcl_GetNumber, Tcl_GetNumberFromObj \- get numeric value from Tcl value
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+\fB#include <tclTomMath.h>\fR
+.sp
+int
+\fBTcl_GetNumber\fR(\fIinterp, bytes, numBytes, clientDataPtr, typePtr\fR)
+.sp
+int
+\fBTcl_GetNumberFromObj\fR(\fIinterp, objPtr, clientDataPtr, typePtr\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp clientDataPtr out
+.AP 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.
+.AP "const char" *bytes in
+Points to first byte of the string value to be examined.
+.AP size_t numBytes in
+The number of bytes, starting at \fIbytes\fR, that should be examined.
+If the value \fBTCL_INDEX_NONE\fR is provided, then all bytes should
+be examined until the first \fBNUL\fR byte terminates examination.
+.AP "void *" *clientDataPtr out
+Points to space where a pointer value may be written through which a numeric
+value is available to read.
+.AP int *typePtr out
+Points to space where a value may be written reporting what type of
+numeric storage is available to read.
+.AP Tcl_Obj *objPtr in
+A Tcl value to be examined.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures enable callers to retrieve a numeric value from a
+Tcl value in a numeric format recognized by Tcl.
+.PP
+Tcl recognizes many values as numbers.  Several examples include:
+\fB"0"\fR, \fB" +1"\fR, \fB"-2 "\fR, \fB" 3 "\fR, \fB"0xdad1"\fR, \fB"0d09"\fR,
+\fB"1_000_000"\fR, \fB"4.0"\fR, \fB"1e-7"\fR, \fB"NaN"\fR, or \fB"Inf"\fR.
+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: \fBdouble\fR, 
+\fBTcl_WideInt\fR, and \fBmp_int\fR.  The \fBdouble\fR type is provided by the
+C language standard.  The \fBTcl_WideInt\fR type is declared in the Tcl
+header file, \fBtcl.h\fR, and is equivalent to the C standard type
+\fBlong long\fR on most platforms. The \fBmp_int\fR type is declared in the
+header file \fBtclTomMath.h\fR, and implemented by the LibTomMath
+multiple-precision integer library, included with Tcl.
+
+The routines \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR perform
+the same function.  They differ only in how the arguments present the Tcl
+value to be examined.  \fBTcl_GetNumber\fR accepts a counted string
+value in the arguments \fIbytes\fR and \fInumBytes\fR (or a
+\fBNUL\fR-terminated string value when \fInumBytes\fR is
+\fBTCL_INDEX_NONE\fR).  \fBTcl_GetNumberFromObj\fR accepts the Tcl value
+in \fIobjPtr\fR.
+
+Both routines examine the Tcl value and determine whether Tcl recognizes
+it as a number.  If not, both routines return \fBTCL_ERROR\fR and (when
+\fIinterp\fR is not NULL) record an error message and error code
+in \fIinterp\fR.
+
+If the examined value is recognized as a number, both routines return
+\fBTCL_OK\fR, and use the pointer arguments \fIclientDataPtr\fR
+and \fItypePtr\fR (which may not be NULL) to report information the
+caller can use to retrieve the numeric representation.  In all cases,
+both routines write to *\fIclientDataPtr\fR a pointer to the internal
+storage location where Tcl holds the numeric value.  When that
+internal storage is of type \fBdouble\fR
+
+
+
+.SH "SEE ALSO"
+Tcl_GetDouble, Tcl_GetDoubleFromObj, Tcl_GetWideIntFromObj
+.SH KEYWORDS
+double, double value, double type, integer, integer value, integer type,
+internal representation, value, value type, string representation
-- 
cgit v0.12


From 9e7c607db1c09acf473b8b10df55452b1e907499 Mon Sep 17 00:00:00 2001
From: dgp <dgp@users.sourceforge.net>
Date: Thu, 29 Sep 2022 20:53:43 +0000
Subject: Complete documentation for the TIP 638 routines.

---
 doc/Number.3 | 53 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 44 insertions(+), 9 deletions(-)

diff --git a/doc/Number.3 b/doc/Number.3
index 65a1332..f93d75d 100644
--- a/doc/Number.3
+++ b/doc/Number.3
@@ -57,7 +57,7 @@ header file, \fBtcl.h\fR, and is equivalent to the C standard type
 \fBlong long\fR on most platforms. The \fBmp_int\fR type is declared in the
 header file \fBtclTomMath.h\fR, and implemented by the LibTomMath
 multiple-precision integer library, included with Tcl.
-
+.PP
 The routines \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR perform
 the same function.  They differ only in how the arguments present the Tcl
 value to be examined.  \fBTcl_GetNumber\fR accepts a counted string
@@ -65,22 +65,57 @@ value in the arguments \fIbytes\fR and \fInumBytes\fR (or a
 \fBNUL\fR-terminated string value when \fInumBytes\fR is
 \fBTCL_INDEX_NONE\fR).  \fBTcl_GetNumberFromObj\fR accepts the Tcl value
 in \fIobjPtr\fR.
-
+.PP
 Both routines examine the Tcl value and determine whether Tcl recognizes
 it as a number.  If not, both routines return \fBTCL_ERROR\fR and (when
 \fIinterp\fR is not NULL) record an error message and error code
 in \fIinterp\fR.
-
-If the examined value is recognized as a number, both routines return
+.PP
+If Tcl does recognize the examined value as a number, both routines return
 \fBTCL_OK\fR, and use the pointer arguments \fIclientDataPtr\fR
 and \fItypePtr\fR (which may not be NULL) to report information the
 caller can use to retrieve the numeric representation.  Both routines
 write to *\fIclientDataPtr\fR a pointer to the internal storage location
-where Tcl holds the converted numeric value.  When that internal storage
-is of type \fBdouble\fR
-
-
-
+where Tcl holds the converted numeric value.  
+.PP
+When the converted numeric value is stored as a \fBdouble\fR,
+a call to math library routine \fBisnan\fR determines whether that
+value is not a number (NaN).  If so, both \fBTcl_GetNumber\fR and
+\fBTcl_GetNumberFromObj\fR write the value \fBTCL_NUMBER_NAN\fR
+to *\fItypePtr\fR. If not, both routines write the value
+\fBTCL_NUMBER_DOUBLE\fR to *\fItypePtr\fR.  These routines report
+different type values in these cases because \fBTcl_GetDoubleFromObj\fR
+raises an error on NaN values.  For both reported type values,
+the storage pointer may be cast to type \fBconst double *\fR and
+the \fBdouble\fR numeric value may be read through it.
+.PP
+When the converted numeric value is stored as a \fBTcl_WideInt\fR,
+both \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR write the
+value \fBTCL_NUMBER_INT\fR to *\fItypePtr\fR. 
+The storage pointer may be cast to type \fBconst Tcl_WideInt *\fR and
+the \fBTcl_WideInt\fR numeric value may be read through it.
+.PP
+When the converted numeric value is stored as an \fBmp_int\fR,
+both \fBTcl_GetNumber\fR and \fBTcl_GetNumberFromObj\fR write the
+value \fBTCL_NUMBER_BIG\fR to *\fItypePtr\fR. 
+The storage pointer may be cast to type \fBconst mp_int *\fR and
+the \fBmp_int\fR numeric value may be read through it.
+.PP
+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
+*\fItypePtr\fR to identify them.  Callers should consider how
+they should react to unknown values written to *\fItypePtr\fR.
+.PP
+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
+\fBTcl_GetNumber\fR or \fBTcl_GetNumberFromObj\fR 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.
 .SH "SEE ALSO"
 Tcl_GetDouble, Tcl_GetDoubleFromObj, Tcl_GetWideIntFromObj
 .SH KEYWORDS
-- 
cgit v0.12