Implementation of TIP #585 - Promote the INDEX_TEMP_TABLE flag of Tcl_GetIndexFromObj*() to the public interface

6 files changed, 26 insertions, 25 deletions

diff --git a/doc/GetIndex.3 b/doc/GetIndex.3
index 17a31d4..8591c56 100644
--- a/doc/GetIndex.3
+++ b/doc/GetIndex.3
@@ -27,19 +27,22 @@ Interpreter to use for error reporting; if NULL, then no message is
 provided on errors.
 .AP Tcl_Obj *objPtr in/out
 The string value of this value is used to search through \fItablePtr\fR.
-The internal representation is modified to hold the index of the matching
+If the \fBTCL_INDEX_TEMP_TABLE\fR flag is not specified,
+the internal representation is modified to hold the index of the matching
 table entry.
 .AP "const char *const" *tablePtr in
 An array of null-terminated strings.  The end of the array is marked
 by a NULL string pointer.
-Note that references to the \fItablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fItablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array.
 .AP "const void" *structTablePtr in
 An array of arbitrary type, typically some \fBstruct\fR type.
 The first member of the structure must be a null-terminated string.
 The size of the structure is given by \fIoffset\fR.
-Note that references to the \fIstructTablePtr\fR may be retained in the
+Note that, unless the \fBTCL_INDEX_TEMP_TABLE\fR flag is specified,
+references to the \fIstructTablePtr\fR may be retained in the
 internal representation of \fIobjPtr\fR, so this should represent the
 address of a statically-allocated array of structures.
 .AP int offset in
@@ -50,7 +53,8 @@ Null-terminated string describing what is being looked up, such as
 \fBoption\fR.  This string is included in error messages.
 .AP int flags in
 OR-ed combination of bits providing additional information for
-operation.  The only bit that is currently defined is \fBTCL_EXACT\fR.
+operation.  The only bits that are currently defined are \fBTCL_EXACT\fR
+and \fBTCL_INDEX_TEMP_TABLE\fR.
 .AP int *indexPtr out
 The index of the string in \fItablePtr\fR that matches the value of
 \fIobjPtr\fR is returned here.
@@ -76,7 +80,8 @@ error message to indicate what was being looked up.  For example,
 if \fImsg\fR is \fBoption\fR the error message will have a form like
 .QW "\fBbad option \N'34'firt\N'34': must be first, second, or third\fR" .
 .PP
-If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
+If the \fBTCL_INDEX_TEMP_TABLE\fR was not specified, when
+\fBTcl_GetIndexFromObj\fR completes successfully it modifies the
 internal representation of \fIobjPtr\fR to hold the address of
 the table and the index of the matching entry.  If \fBTcl_GetIndexFromObj\fR
 is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR
@@ -84,7 +89,9 @@ arguments (e.g. during a reinvocation of a Tcl command), it returns
 the matching index immediately without having to redo the lookup
 operation.  Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
 in \fItablePtr\fR are static: they must not change between
-invocations.  If the value of \fIobjPtr\fR is the empty string,
+invocations.  This caching mechanism can be disallowed by specifying
+the \fBTCL_INDEX_TEMP_TABLE\fR flag.
+If the value of \fIobjPtr\fR is the empty string,
 \fBTcl_GetIndexFromObj\fR will treat it as a non-matching value
 and return \fBTCL_ERROR\fR.
 .PP
diff --git a/generic/tcl.h b/generic/tcl.h
index 02ef01e..65169c0 100644
--- a/generic/tcl.h
+++ b/generic/tcl.h
@@ -973,11 +973,14 @@ typedef struct Tcl_DString {
 #define TCL_DONT_QUOTE_HASH	8
 
 /*
- * Flag that may be passed to Tcl_GetIndexFromObj to force it to disallow
- * abbreviated strings.
+ * Flags that may be passed to Tcl_GetIndexFromObj.
+ * TCL_EXACT disallows abbreviated strings.
+ * TCL_INDEX_TEMP_TABLE disallows caching of lookups. A possible use case is
+ *      a table that will not live long enough to make it worthwhile.
  */
 
-#define TCL_EXACT	1
+#define TCL_EXACT		1
+#define TCL_INDEX_TEMP_TABLE	2
 
 /*
  *----------------------------------------------------------------------------
diff --git a/generic/tclFCmd.c b/generic/tclFCmd.c
index 3babd43..d6a152a 100644
--- a/generic/tclFCmd.c
+++ b/generic/tclFCmd.c
@@ -1085,7 +1085,7 @@ TclFileAttrsCmd(
 	}
 
 	if (Tcl_GetIndexFromObj(interp, objv[0], attributeStrings,
-		"option", INDEX_TEMP_TABLE, &index) != TCL_OK) {
+		"option", TCL_INDEX_TEMP_TABLE, &index) != TCL_OK) {
 	    goto end;
 	}
 	if (Tcl_FSFileAttrsGet(interp, index, filePtr,
@@ -1110,7 +1110,7 @@ TclFileAttrsCmd(
 
 	for (i = 0; i < objc ; i += 2) {
 	    if (Tcl_GetIndexFromObj(interp, objv[i], attributeStrings,
-		    "option", INDEX_TEMP_TABLE, &index) != TCL_OK) {
+		    "option", TCL_INDEX_TEMP_TABLE, &index) != TCL_OK) {
 		goto end;
 	    }
 	    if (i + 1 == objc) {
diff --git a/generic/tclIndexObj.c b/generic/tclIndexObj.c
index 4749e6e..a0a31da 100644
--- a/generic/tclIndexObj.c
+++ b/generic/tclIndexObj.c
@@ -114,7 +114,7 @@ Tcl_GetIndexFromObj(
     int flags,			/* 0 or TCL_EXACT */
     int *indexPtr)		/* Place to store resulting integer index. */
 {
-    if (!(flags & INDEX_TEMP_TABLE)) {
+    if (!(flags & TCL_INDEX_TEMP_TABLE)) {
 
     /*
      * See if there is a valid cached result from a previous lookup (doing the
@@ -216,7 +216,7 @@ GetIndexFromObjList(
     tablePtr[objc] = NULL;
 
     result = Tcl_GetIndexFromObjStruct(interp, objPtr, tablePtr,
-	    sizeof(char *), msg, flags | INDEX_TEMP_TABLE, indexPtr);
+	    sizeof(char *), msg, flags | TCL_INDEX_TEMP_TABLE, indexPtr);
 
     ckfree(tablePtr);
 
@@ -280,7 +280,7 @@ Tcl_GetIndexFromObjStruct(
      * See if there is a valid cached result from a previous lookup.
      */
 
-    if (!(flags & INDEX_TEMP_TABLE)) {
+    if (!(flags & TCL_INDEX_TEMP_TABLE)) {
     irPtr = TclFetchIntRep(objPtr, &indexType);
     if (irPtr) {
 	indexRep = (IndexRep *)irPtr->twoPtrValue.ptr1;
@@ -344,7 +344,7 @@ Tcl_GetIndexFromObjStruct(
      * operation.
      */
 
-    if (!(flags & INDEX_TEMP_TABLE)) {
+    if (!(flags & TCL_INDEX_TEMP_TABLE)) {
     irPtr = TclFetchIntRep(objPtr, &indexType);
     if (irPtr) {
 	indexRep = (IndexRep *)irPtr->twoPtrValue.ptr1;
diff --git a/generic/tclInt.h b/generic/tclInt.h
index 2f12b8f..7791a1c 100644
--- a/generic/tclInt.h
+++ b/generic/tclInt.h
@@ -2606,15 +2606,6 @@ typedef struct TclFileAttrProcs {
 } TclFileAttrProcs;
 
 /*
- * Private flag value which controls Tcl_GetIndexFromObj*() routines
- * to instruct them not to cache lookups because the table will not
- * live long enough to make it worthwhile.  Must not clash with public
- * flag value TCL_EXACT.
- */
-
-#define INDEX_TEMP_TABLE 2
-
-/*
  * Opaque handle used in pipeline routines to encapsulate platform-dependent
  * state.
  */
diff --git a/generic/tclTestObj.c b/generic/tclTestObj.c
index 99cb1f4..bd5d92e 100644
--- a/generic/tclTestObj.c
+++ b/generic/tclTestObj.c
@@ -627,7 +627,7 @@ TestindexobjCmd(
     argv[objc-4] = NULL;
 
     result = Tcl_GetIndexFromObj((setError? interp : NULL), objv[3],
-	    argv, "token", INDEX_TEMP_TABLE|(allowAbbrev? 0 : TCL_EXACT),
+	    argv, "token", TCL_INDEX_TEMP_TABLE|(allowAbbrev? 0 : TCL_EXACT),
 	    &index);
     ckfree(argv);
     if (result == TCL_OK) {