TIP #544 implementation: Export TclGetIntForIndex()

9 files changed, 42 insertions, 10 deletions

diff --git a/doc/IntObj.3 b/doc/IntObj.3
index 6d5ee69..e793303 100644
--- a/doc/IntObj.3
+++ b/doc/IntObj.3
@@ -8,7 +8,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
+Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -32,6 +32,9 @@ int
 \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
 .sp
 int
+\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR)
+.sp
+int
 \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
 .sp
 int
@@ -55,6 +58,8 @@ int
 \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
 .SH ARGUMENTS
 .AS Tcl_WideInt doubleValue in/out
+.AP int endValue in
+\fBTcl_GetIntForIndex\fR will return this when the input value is "end".
 .AP int intValue in
 Integer value used to initialize or set a Tcl value.
 .AP long longValue in
@@ -115,6 +120,16 @@ 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
+The \fBTcl_GetIntForIndex\fR routine attempts to retrieve an index
+value from the Tcl value \fIobjPtr\fR.  If the attempt succeeds,
+then \fBTCL_OK\fR is returned, and the value is written to the
+storage provided by the caller.  The attempt might fail if
+\fIobjPtr\fR does not hold an index value.  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 the
+same routine more efficient.
+.PP
 The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
 \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
 \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
diff --git a/generic/tcl.decls b/generic/tcl.decls
index 7d3b535..19672a7 100644
--- a/generic/tcl.decls
+++ b/generic/tcl.decls
@@ -2385,6 +2385,11 @@ declare 644 {
 	    int type, int size)
 }
 
+declare 645 {
+    int Tcl_GetIntForIndex(Tcl_Interp *interp, Tcl_Obj *objPtr,
+	    int endValue, int *indexPtr)
+}
+
 # ----- BASELINE -- FOR -- 8.7.0 ----- #
 
 ##############################################################################
diff --git a/generic/tcl.h b/generic/tcl.h
index e34a609..cd194d1 100644
--- a/generic/tcl.h
+++ b/generic/tcl.h
@@ -2329,6 +2329,7 @@ typedef int (Tcl_ArgvGenFuncProc)(ClientData clientData, Tcl_Interp *interp,
 
 #define TCL_IO_FAILURE	(-1)
 #define TCL_AUTO_LENGTH	(-1)
+#define TCL_INDEX_NONE	(-1)
 
 /*
  *----------------------------------------------------------------------------
diff --git a/generic/tclDecls.h b/generic/tclDecls.h
index 3d40bef..3f39cd5 100644
--- a/generic/tclDecls.h
+++ b/generic/tclDecls.h
@@ -1901,6 +1901,9 @@ EXTERN int		Tcl_IsShared(Tcl_Obj *objPtr);
 EXTERN int		Tcl_LinkArray(Tcl_Interp *interp,
 				const char *varName, void *addr, int type,
 				int size);
+/* 645 */
+EXTERN int		Tcl_GetIntForIndex(Tcl_Interp *interp,
+				Tcl_Obj *objPtr, int endValue, int *indexPtr);
 
 typedef struct {
     const struct TclPlatStubs *tclPlatStubs;
@@ -2581,6 +2584,7 @@ typedef struct TclStubs {
     void (*tcl_DecrRefCount) (Tcl_Obj *objPtr); /* 642 */
     int (*tcl_IsShared) (Tcl_Obj *objPtr); /* 643 */
     int (*tcl_LinkArray) (Tcl_Interp *interp, const char *varName, void *addr, int type, int size); /* 644 */
+    int (*tcl_GetIntForIndex) (Tcl_Interp *interp, Tcl_Obj *objPtr, int endValue, int *indexPtr); /* 645 */
 } TclStubs;
 
 extern const TclStubs *tclStubsPtr;
@@ -3901,6 +3905,8 @@ extern const TclStubs *tclStubsPtr;
 	(tclStubsPtr->tcl_IsShared) /* 643 */
 #define Tcl_LinkArray \
 	(tclStubsPtr->tcl_LinkArray) /* 644 */
+#define Tcl_GetIntForIndex \
+	(tclStubsPtr->tcl_GetIntForIndex) /* 645 */
 
 #endif /* defined(USE_TCL_STUBS) */
 
diff --git a/generic/tclInt.decls b/generic/tclInt.decls
index 3870f3d..556da28 100644
--- a/generic/tclInt.decls
+++ b/generic/tclInt.decls
@@ -151,7 +151,7 @@ declare 32 {
 #declare 33 {
 #    TclCmdProcType TclGetInterpProc(void)
 #}
-declare 34 {
+declare 34 {deprecated {Use Tcl_GetIntForIndex}} {
     int TclGetIntForIndex(Tcl_Interp *interp, Tcl_Obj *objPtr,
 	    int endValue, int *indexPtr)
 }
diff --git a/generic/tclInt.h b/generic/tclInt.h
index a2d19f9..933280a 100644
--- a/generic/tclInt.h
+++ b/generic/tclInt.h
@@ -2477,7 +2477,7 @@ typedef struct List {
 /*
  * Macros providing a faster path to booleans and integers:
  * Tcl_GetBooleanFromObj, Tcl_GetLongFromObj, Tcl_GetIntFromObj
- * and TclGetIntForIndex.
+ * and Tcl_GetIntForIndex.
  *
  * WARNING: these macros eval their args more than once.
  */
@@ -2514,7 +2514,7 @@ typedef struct List {
 	    && (objPtr)->internalRep.wideValue <= (Tcl_WideInt)(INT_MAX)) \
 	    ? ((*(idxPtr) = ((objPtr)->internalRep.wideValue >= 0) \
 	    ? (int)(objPtr)->internalRep.wideValue : -1), TCL_OK) \
-	    : TclGetIntForIndex((interp), (objPtr), (endValue), (idxPtr)))
+	    : Tcl_GetIntForIndex((interp), (objPtr), (endValue), (idxPtr)))
 
 /*
  * Macro used to save a function call for common uses of
@@ -4204,7 +4204,6 @@ MODULE_SCOPE int	TclIndexDecode(int encoded, int endValue);
 
 /* Constants used in index value encoding routines. */
 #define TCL_INDEX_END           (-2)
-#define TCL_INDEX_NONE          (-1) /* Index out of range or END+1 */
 #define TCL_INDEX_START         (0)
 
 /*
diff --git a/generic/tclIntDecls.h b/generic/tclIntDecls.h
index 56abe77..16bcdf8 100644
--- a/generic/tclIntDecls.h
+++ b/generic/tclIntDecls.h
@@ -28,6 +28,7 @@
 #endif
 
 #if !defined(TCL_NO_DEPRECATED) && (TCL_MAJOR_VERSION < 9)
+#   define tclGetIntForIndex tcl_GetIntForIndex
 /* Those macro's are especially for Itcl 3.4 compatibility */
 #   define tclCreateNamespace tcl_CreateNamespace
 #   define tclDeleteNamespace tcl_DeleteNamespace
@@ -129,7 +130,8 @@ EXTERN int		TclGetFrame(Tcl_Interp *interp, const char *str,
 				CallFrame **framePtrPtr);
 /* Slot 33 is reserved */
 /* 34 */
-EXTERN int		TclGetIntForIndex(Tcl_Interp *interp,
+TCL_DEPRECATED("Use Tcl_GetIntForIndex")
+int			TclGetIntForIndex(Tcl_Interp *interp,
 				Tcl_Obj *objPtr, int endValue, int *indexPtr);
 /* Slot 35 is reserved */
 /* Slot 36 is reserved */
@@ -695,7 +697,7 @@ typedef struct TclIntStubs {
     const char * (*tclGetExtension) (const char *name); /* 31 */
     int (*tclGetFrame) (Tcl_Interp *interp, const char *str, CallFrame **framePtrPtr); /* 32 */
     void (*reserved33)(void);
-    int (*tclGetIntForIndex) (Tcl_Interp *interp, Tcl_Obj *objPtr, int endValue, int *indexPtr); /* 34 */
+    TCL_DEPRECATED_API("Use Tcl_GetIntForIndex") int (*tclGetIntForIndex) (Tcl_Interp *interp, Tcl_Obj *objPtr, int endValue, int *indexPtr); /* 34 */
     void (*reserved35)(void);
     void (*reserved36)(void);
     int (*tclGetLoadedPackages) (Tcl_Interp *interp, const char *targetName); /* 37 */
@@ -1381,6 +1383,7 @@ extern const TclIntStubs *tclIntStubsPtr;
 #   undef TclBackgroundException
 #   undef TclSetStartupScript
 #   undef TclGetStartupScript
+#   undef TclGetIntForIndex
 #   undef TclCreateNamespace
 #   undef TclDeleteNamespace
 #   undef TclAppendExportList
diff --git a/generic/tclStubInit.c b/generic/tclStubInit.c
index 74d02f1..5e918f5 100644
--- a/generic/tclStubInit.c
+++ b/generic/tclStubInit.c
@@ -394,6 +394,7 @@ static int uniCharNcasecmp(const Tcl_UniChar *ucs, const Tcl_UniChar *uct, unsig
 #   define TclpReaddir 0
 #   define TclSetStartupScript 0
 #   define TclGetStartupScript 0
+#   define TclGetIntForIndex 0
 #   define TclCreateNamespace 0
 #   define TclDeleteNamespace 0
 #   define TclAppendExportList 0
@@ -444,6 +445,7 @@ static int uniCharNcasecmp(const Tcl_UniChar *ucs, const Tcl_UniChar *uct, unsig
 #   define TclBackgroundException Tcl_BackgroundException
 #   define TclSetStartupScript Tcl_SetStartupScript
 #   define TclGetStartupScript Tcl_GetStartupScript
+#   define TclGetIntForIndex Tcl_GetIntForIndex
 #   define TclCreateNamespace Tcl_CreateNamespace
 #   define TclDeleteNamespace Tcl_DeleteNamespace
 #   define TclAppendExportList Tcl_AppendExportList
@@ -1639,6 +1641,7 @@ const TclStubs tclStubs = {
     Tcl_DecrRefCount, /* 642 */
     Tcl_IsShared, /* 643 */
     Tcl_LinkArray, /* 644 */
+    Tcl_GetIntForIndex, /* 645 */
 };
 
 /* !END!: Do not edit above this line. */
diff --git a/generic/tclUtil.c b/generic/tclUtil.c
index 2889852..4387c75 100644
--- a/generic/tclUtil.c
+++ b/generic/tclUtil.c
@@ -121,7 +121,7 @@ static int		FindElement(Tcl_Interp *interp, const char *string,
 /*
  * The following is the Tcl object type definition for an object that
  * represents a list index in the form, "end-offset". It is used as a
- * performance optimization in TclGetIntForIndex. The internal rep is
+ * performance optimization in Tcl_GetIntForIndex. The internal rep is
  * stored directly in the wideValue, so no memory management is required
  * for it. This is a caching intrep, keeping the result of a parse
  * around. This type is only created from a pre-existing string, so an
@@ -3872,7 +3872,7 @@ GetWideForIndex(
 /*
  *----------------------------------------------------------------------
  *
- * TclGetIntForIndex --
+ * Tcl_GetIntForIndex --
  *
  *	This function returns an integer corresponding to the list index held
  *	in a Tcl object. The Tcl object's value is expected to be in the
@@ -3894,7 +3894,7 @@ GetWideForIndex(
  */
 
 int
-TclGetIntForIndex(
+Tcl_GetIntForIndex(
     Tcl_Interp *interp,		/* Interpreter to use for error reporting. If
 				 * NULL, then no error message is left after
 				 * errors. */