2000-01-18 Andreas Kupries <a.kupries@westend.com>

	* Everything below belongs together, it fixes bug #123153.

	* generic/tcl.h (line 342): A bit more explanation about the
	  default value for TCL_PRESERVE_BINARY_COMPATABILITY.

	* generic/tcl.h (line 1208): Removed the macro 'Tcl_InitHashTable'
	  as it kills binary compatibility to 8.3 and earlier
	  versions. This is the main part of the patch/change.

	* generic/tcl.decls (line 1469):
	* generic/tclHash.c (Tcl_InitHashTable):
	* generic/tclHash.c (Tcl_InitHashTableEx):
	* generic/tclObj.c (Tcl_InitObjHashTable): Changed
	  'Tcl_InitHashTableEx' to 'Tcl_InitCustomHashTable'. This change
	  is more of an estethical nature, replacing the ubiquitous 'Ex'
	  suffix with a more meaningful name. The introduced binary
	  incompatibility is deemed acceptable as it is between alpha
	  versions.  Updated callers.

	* doc/Hash.3:
	* unix/mkLinks: Changed 'Tcl_InitHashTableEx' to
	  'Tcl_InitCustomHashTable'.

9 files changed, 98 insertions, 67 deletions

diff --git a/ChangeLog b/ChangeLog
index 3127997..b1bb8f7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,28 @@
+2000-01-18  Andreas Kupries  <a.kupries@westend.com>
+
+	* Everything below belongs together, it fixes bug #123153.
+
+	* generic/tcl.h (line 342): A bit more explanation about the
+	  default value for TCL_PRESERVE_BINARY_COMPATABILITY.
+
+	* generic/tcl.h (line 1208): Removed the macro 'Tcl_InitHashTable'
+	  as it kills binary compatibility to 8.3 and earlier
+	  versions. This is the main part of the patch/change.
+
+	* generic/tcl.decls (line 1469):
+	* generic/tclHash.c (Tcl_InitHashTable):
+	* generic/tclHash.c (Tcl_InitHashTableEx):
+	* generic/tclObj.c (Tcl_InitObjHashTable): Changed
+	  'Tcl_InitHashTableEx' to 'Tcl_InitCustomHashTable'. This change
+	  is more of an estethical nature, replacing the ubiquitous 'Ex'
+	  suffix with a more meaningful name. The introduced binary
+	  incompatibility is deemed acceptable as it is between alpha
+	  versions.  Updated callers.
+
+	* doc/Hash.3:
+	* unix/mkLinks: Changed 'Tcl_InitHashTableEx' to
+	  'Tcl_InitCustomHashTable'.
+
 2001-01-10  Donal K. Fellows  <fellowsd@cs.man.ac.uk>
 
 	* tests/winPipe.test (winpipe-1.20): 
@@ -19,6 +44,7 @@
 	[Bug 119416, Patch 102972]
 
 2000-12-14  Don Porter  <dgp@users.sourceforge.net>
+
 	* generic/tclExecute.c:
 	* tests/expr-old.test:  Re-wrote Tcl's [expr rand()] and
 	[expr srand($seed)] implementations, fixing a range error
diff --git a/doc/Hash.3 b/doc/Hash.3
index 7cbd243..7fbb7b2 100644
--- a/doc/Hash.3
+++ b/doc/Hash.3
@@ -5,20 +5,20 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Hash.3,v 1.7 2000/07/22 01:53:23 ericm Exp $
+'\" RCS: @(#) $Id: Hash.3,v 1.8 2001/01/18 19:09:55 andreas_kupries Exp $
 '\" 
 .so man.macros
 .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_InitHashTable, Tcl_InitHashTableEx, Tcl_InitObjHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables
+Tcl_InitHashTable, Tcl_InitCustomHashTable, Tcl_InitObjHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 \fBTcl_InitHashTable\fR(\fItablePtr, keyType\fR)
 .sp
-\fBTcl_InitHashTableEx\fR(\fItablePtr, keyType, typePtr\fR)
+\fBTcl_InitCustomHashTable\fR(\fItablePtr, keyType, typePtr\fR)
 .sp
 \fBTcl_InitObjHashTable\fR(\fItablePtr\fR)
 .sp
@@ -75,43 +75,49 @@ ClientData, but must fit in same space as ClientData.
 Pointer to record to use to keep track of progress in enumerating
 all the entries in a hash table.
 .BE
-
 .SH DESCRIPTION
 .PP
-A hash table consists of zero or more entries, each consisting of
-a key and a value.
-Given the key for an entry, the hashing routines can very quickly
-locate the entry, and hence its value.
-There may be at most one entry in a hash table with a
-particular key, but many entries may have the same value.
-Keys can take one of three forms:  strings,
-one-word values, or integer arrays.
-All of the keys in a given table have the same form, which is
-specified when the table is initialized.
+A hash table consists of zero or more entries, each consisting of a
+key and a value.  Given the key for an entry, the hashing routines can
+very quickly locate the entry, and hence its value. There may be at
+most one entry in a hash table with a particular key, but many entries
+may have the same value.  Keys can take one of four forms: strings,
+one-word values, integer arrays, or custom keys defined by a
+Tcl_HashKeyType structure (See section \fBTHE TCL_HASHKEYTYPE
+STRUCTURE\fR below). All of the keys in a given table have the same
+form, which is specified when the table is initialized.
 .PP
-The value of a hash table entry can be anything that fits in
-the same space as a ``char *'' pointer.
-Values for hash table entries are managed entirely by clients,
-not by the hash module itself.
-Typically each entry's value is a pointer to a data structure
-managed by client code.
+The value of a hash table entry can be anything that fits in the same
+space as a ``char *'' pointer.  Values for hash table entries are
+managed entirely by clients, not by the hash module itself.  Typically
+each entry's value is a pointer to a data structure managed by client
+code.
 .PP
-Hash tables grow gracefully as the number of entries increases,
-so that there are always less than three entries per hash bucket,
-on average.
-This allows for fast lookups regardless of the number of entries
-in a table.
+Hash tables grow gracefully as the number of entries increases, so
+that there are always less than three entries per hash bucket, on
+average. This allows for fast lookups regardless of the number of
+entries in a table.
 .PP
-\fBTcl_InitHashTable\fR calls the extended function 
-\fBTcl_InitHashTableEx\fR with a NULL \fItypePtr\fR.
+The core provides three functions for the initialization of hash
+tables, Tcl_InitHashTable, Tcl_InitObjHashTable and
+Tcl_InitCustomHashTable.
 .PP
-\fBTcl_InitHashTableEx\fR initializes a structure that describes
-a new hash table.
-The space for the structure is provided by the caller, not by
-the hash module.
-The value of \fIkeyType\fR indicates what kinds of keys will
-be used for all entries in the table.  \fIKeyType\fR must have
-one of the following values:
+\fBTcl_InitHashTable\fR initializes a structure that describes a new
+hash table.  The space for the structure is provided by the caller,
+not by the hash module.  The value of \fIkeyType\fR indicates what
+kinds of keys will be used for all entries in the table. All of the
+key types described later are allowed, with the exception of
+\fBTCL_CUSTOM_TYPE_KEYS\fR and \fBTCL_CUSTOM_PTR_KEYS\fR.
+.PP
+\fBTcl_InitObjHashTable\fR is a wrapper around
+\fBTcl_InitCustomHashTable\fR and initializes a hash table whose keys
+are Tcl_Obj *.
+.PP
+\fBTcl_InitCustomHashTable\fR initializes a structure that describes a
+new hash table. The space for the structure is provided by the
+caller, not by the hash module.  The value of \fIkeyType\fR indicates
+what kinds of keys will be used for all entries in the table.
+\fIKeyType\fR must have one of the following values:
 .IP \fBTCL_STRING_KEYS\fR 25
 Keys are null-terminated ASCII strings.
 They are passed to hashing routines using the address of the
@@ -126,9 +132,8 @@ Keys are of arbitrary type, and are stored in the entry. Hashing
 and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType 
 structure is described in the section 
 \fBTHE TCL_HASHKEYTYPE STRUCTURE\fR below.
-
-.IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25
-Keys are pointers to arbitrary type, and the are stored in the entry. Hashing
+.IP \fBTCL_CUSTOM_PTR_KEYS\fR 25
+Keys are pointers to an arbitrary type, and are stored in the entry. Hashing
 and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType 
 structure is described in the section 
 \fBTHE TCL_HASHKEYTYPE STRUCTURE\fR below.
@@ -142,9 +147,6 @@ All keys must have the same size.
 Array keys are passed into hashing functions using the address
 of the first int in the array.
 .PP
-\fBTcl_InitObjHashTable\fR uses \fBTcl_InitHashTableEx\fR to
-initialize a hash table whose keys are Tcl_Obj *.
-.PP
 \fBTcl_DeleteHashTable\fR deletes all of the entries in a hash
 table and frees up the memory associated with the table's
 bucket array and entries.
@@ -226,12 +228,11 @@ the values of entries.
 However, users of the hashing routines should never refer directly
 to any of the fields of any of the hash-related data structures;
 use the procedures and macros defined here.
-
 .SH "THE TCL_HASHKEYTYPE STRUCTURE"
 .PP
 Extension writers can define new hash key types by defining four
-procedure, initializing a Tcl_HashKeyType structure to describe
-the type, and calling \fBTcl_InitHashTableEx\fR.
+procedures, initializing a Tcl_HashKeyType structure to describe
+the type, and calling \fBTcl_InitCustomHashTable\fR.
 The \fBTcl_HashKeyType\fR structure is defined as follows:
 .CS
 typedef struct Tcl_HashKeyType {
@@ -249,7 +250,7 @@ structure is extended in future then the version can be used
 to distinguish between different structures. It should be set
 to \fBTCL_HASH_KEY_TYPE_VERSION\fR.
 .PP
-The \fIflags\fR member is one or more of the following OR'ed together:
+The \fIflags\fR member is one or more of the following values OR'ed together:
 .IP \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR 25
 There are some things, pointers for example which don't hash well 
 because they do not use the lower bits. If this flag is set then the
diff --git a/generic/tcl.decls b/generic/tcl.decls
index 28905ca..6c1e790 100644
--- a/generic/tcl.decls
+++ b/generic/tcl.decls
@@ -10,7 +10,7 @@
 # See the file "license.terms" for information on usage and redistribution
 # of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 # 
-# RCS: @(#) $Id: tcl.decls,v 1.42 2000/11/03 18:46:10 hobbs Exp $
+# RCS: @(#) $Id: tcl.decls,v 1.43 2001/01/18 19:09:55 andreas_kupries Exp $
 
 library tcl
 
@@ -1466,7 +1466,7 @@ declare 422 generic {
 }
 
 declare 423 generic {
-    void Tcl_InitHashTableEx(Tcl_HashTable *tablePtr, int keyType, \
+    void Tcl_InitCustomHashTable(Tcl_HashTable *tablePtr, int keyType, \
 	    Tcl_HashKeyType *typePtr)
 }
 
diff --git a/generic/tcl.h b/generic/tcl.h
index c8f527e..1c7160c 100644
--- a/generic/tcl.h
+++ b/generic/tcl.h
@@ -12,7 +12,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tcl.h,v 1.85 2000/12/08 04:22:43 ericm Exp $
+ * RCS: @(#) $Id: tcl.h,v 1.86 2001/01/18 19:09:55 andreas_kupries Exp $
  */
 
 #ifndef _TCL
@@ -339,7 +339,8 @@ typedef long LONG;
 
 /*
  * This flag controls whether binary compatability is maintained with
- * extensions built against a previous version of Tcl.
+ * extensions built against a previous version of Tcl. This is true
+ * by default.
  */
 #ifndef TCL_PRESERVE_BINARY_COMPATABILITY
 #define TCL_PRESERVE_BINARY_COMPATABILITY 1
@@ -1206,12 +1207,14 @@ typedef struct Tcl_HashSearch {
 	(*((tablePtr)->createProc))(tablePtr, key, newPtr)
 #endif
 
+#if !TCL_PRESERVE_BINARY_COMPATABILITY
 /*
  * Macro to use new extended version of Tcl_InitHashTable.
  */
 #define Tcl_InitHashTable(tablePtr, keyType) \
 	Tcl_InitHashTableEx(tablePtr, keyType, NULL)
-    
+#endif
+
 /*
  * Flag values to pass to Tcl_DoOneEvent to disable searches
  * for some kinds of events:
diff --git a/generic/tclDecls.h b/generic/tclDecls.h
index 743cef2..869100f 100644
--- a/generic/tclDecls.h
+++ b/generic/tclDecls.h
@@ -8,7 +8,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclDecls.h,v 1.43 2000/11/03 18:46:11 hobbs Exp $
+ * RCS: @(#) $Id: tclDecls.h,v 1.44 2001/01/18 19:09:55 andreas_kupries Exp $
  */
 
 #ifndef _TCLDECLS
@@ -1315,7 +1315,7 @@ EXTERN Tcl_HashEntry *	Tcl_CreateHashEntry _ANSI_ARGS_((
 				Tcl_HashTable * tablePtr, CONST char * key, 
 				int * newPtr));
 /* 423 */
-EXTERN void		Tcl_InitHashTableEx _ANSI_ARGS_((
+EXTERN void		Tcl_InitCustomHashTable _ANSI_ARGS_((
 				Tcl_HashTable * tablePtr, int keyType, 
 				Tcl_HashKeyType * typePtr));
 /* 424 */
@@ -1840,7 +1840,7 @@ typedef struct TclStubs {
     int (*tcl_UniCharCaseMatch) _ANSI_ARGS_((CONST Tcl_UniChar * ustr, CONST Tcl_UniChar * pattern, int nocase)); /* 420 */
     Tcl_HashEntry * (*tcl_FindHashEntry) _ANSI_ARGS_((Tcl_HashTable * tablePtr, CONST char * key)); /* 421 */
     Tcl_HashEntry * (*tcl_CreateHashEntry) _ANSI_ARGS_((Tcl_HashTable * tablePtr, CONST char * key, int * newPtr)); /* 422 */
-    void (*tcl_InitHashTableEx) _ANSI_ARGS_((Tcl_HashTable * tablePtr, int keyType, Tcl_HashKeyType * typePtr)); /* 423 */
+    void (*Tcl_InitCustomHashTable) _ANSI_ARGS_((Tcl_HashTable * tablePtr, int keyType, Tcl_HashKeyType * typePtr)); /* 423 */
     void (*tcl_InitObjHashTable) _ANSI_ARGS_((Tcl_HashTable * tablePtr)); /* 424 */
     ClientData (*tcl_CommandTraceInfo) _ANSI_ARGS_((Tcl_Interp * interp, char * varName, int flags, Tcl_CommandTraceProc * procPtr, ClientData prevClientData)); /* 425 */
     int (*tcl_TraceCommand) _ANSI_ARGS_((Tcl_Interp * interp, char * varName, int flags, Tcl_CommandTraceProc * proc, ClientData clientData)); /* 426 */
@@ -3590,9 +3590,9 @@ extern TclStubs *tclStubsPtr;
 #define Tcl_CreateHashEntry \
 	(tclStubsPtr->tcl_CreateHashEntry) /* 422 */
 #endif
-#ifndef Tcl_InitHashTableEx
-#define Tcl_InitHashTableEx \
-	(tclStubsPtr->tcl_InitHashTableEx) /* 423 */
+#ifndef Tcl_InitCustomHashTable
+#define Tcl_InitCustomHashTable \
+	(tclStubsPtr->Tcl_InitCustomHashTable) /* 423 */
 #endif
 #ifndef Tcl_InitObjHashTable
 #define Tcl_InitObjHashTable \
diff --git a/generic/tclHash.c b/generic/tclHash.c
index 8a0f1dc..a1075c5 100644
--- a/generic/tclHash.c
+++ b/generic/tclHash.c
@@ -10,7 +10,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclHash.c,v 1.8 2000/09/06 16:57:27 hobbs Exp $
+ * RCS: @(#) $Id: tclHash.c,v 1.9 2001/01/18 19:09:55 andreas_kupries Exp $
  */
 
 #include "tclInt.h"
@@ -157,17 +157,17 @@ Tcl_InitHashTable(tablePtr, keyType)
      * extension is rebuilt then any calls to this function will be
      * redirected to the extended version by a macro.
      */
-    Tcl_InitHashTableEx(tablePtr, keyType, (Tcl_HashKeyType *) -1);
+    Tcl_InitCustomHashTable(tablePtr, keyType, (Tcl_HashKeyType *) -1);
 }
 
 /*
  *----------------------------------------------------------------------
  *
- * Tcl_InitHashTableEx --
+ * Tcl_InitCustomHashTable --
  *
  *	Given storage for a hash table, set up the fields to prepare
  *	the hash table for use. This is an extended version of
- *	Tcl_InitHashTableEx which supports user defined keys.
+ *	Tcl_InitHashTable which supports user defined keys.
  *
  * Results:
  *	None.
@@ -180,7 +180,7 @@ Tcl_InitHashTable(tablePtr, keyType)
  */
 
 void
-Tcl_InitHashTableEx(tablePtr, keyType, typePtr)
+Tcl_InitCustomHashTable(tablePtr, keyType, typePtr)
     register Tcl_HashTable *tablePtr;	/* Pointer to table record, which
 					 * is supplied by the caller. */
     int keyType;			/* Type of keys to use in table:
@@ -192,7 +192,7 @@ Tcl_InitHashTableEx(tablePtr, keyType, typePtr)
 					 * the behaviour of this table. */
 {
 #if (TCL_SMALL_HASH_TABLE != 4) 
-    panic("Tcl_InitHashTableEx: TCL_SMALL_HASH_TABLE is %d, not 4\n",
+    panic("Tcl_InitCustomHashTable: TCL_SMALL_HASH_TABLE is %d, not 4\n",
 	    TCL_SMALL_HASH_TABLE);
 #endif
     
diff --git a/generic/tclObj.c b/generic/tclObj.c
index d5d3821..e2a9bae 100644
--- a/generic/tclObj.c
+++ b/generic/tclObj.c
@@ -10,7 +10,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclObj.c,v 1.18 2000/08/10 18:24:52 davidg Exp $
+ * RCS: @(#) $Id: tclObj.c,v 1.19 2001/01/18 19:09:55 andreas_kupries Exp $
  */
 
 #include "tclInt.h"
@@ -2148,7 +2148,8 @@ Tcl_InitObjHashTable(tablePtr)
     register Tcl_HashTable *tablePtr;	/* Pointer to table record, which
 					 * is supplied by the caller. */
 {
-    Tcl_InitHashTableEx (tablePtr, TCL_CUSTOM_PTR_KEYS, &tclObjHashKeyType);
+    Tcl_InitCustomHashTable(tablePtr, TCL_CUSTOM_PTR_KEYS,
+	    &tclObjHashKeyType);
 }
 
 /*
diff --git a/generic/tclStubInit.c b/generic/tclStubInit.c
index 263e2a8..cb42cc0 100644
--- a/generic/tclStubInit.c
+++ b/generic/tclStubInit.c
@@ -8,7 +8,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclStubInit.c,v 1.46 2000/11/03 18:46:12 hobbs Exp $
+ * RCS: @(#) $Id: tclStubInit.c,v 1.47 2001/01/18 19:09:55 andreas_kupries Exp $
  */
 
 #include "tclInt.h"
@@ -826,7 +826,7 @@ TclStubs tclStubs = {
     Tcl_UniCharCaseMatch, /* 420 */
     Tcl_FindHashEntry, /* 421 */
     Tcl_CreateHashEntry, /* 422 */
-    Tcl_InitHashTableEx, /* 423 */
+    Tcl_InitCustomHashTable, /* 423 */
     Tcl_InitObjHashTable, /* 424 */
     Tcl_CommandTraceInfo, /* 425 */
     Tcl_TraceCommand, /* 426 */
diff --git a/unix/mkLinks b/unix/mkLinks
index 5337055..4cb02cb 100644
--- a/unix/mkLinks
+++ b/unix/mkLinks
@@ -472,7 +472,7 @@ if test -r GetVersion.3; then
 fi
 if test -r Hash.3; then
     rm -f Tcl_InitHashTable.3
-    rm -f Tcl_InitHashTableEx.3
+    rm -f Tcl_InitCustomHashTable.3
     rm -f Tcl_InitObjHashTable.3
     rm -f Tcl_DeleteHashTable.3
     rm -f Tcl_CreateHashEntry.3
@@ -485,7 +485,7 @@ if test -r Hash.3; then
     rm -f Tcl_NextHashEntry.3
     rm -f Tcl_HashStats.3
     ln Hash.3 Tcl_InitHashTable.3
-    ln Hash.3 Tcl_InitHashTableEx.3
+    ln Hash.3 Tcl_InitCustomHashTable.3
     ln Hash.3 Tcl_InitObjHashTable.3
     ln Hash.3 Tcl_DeleteHashTable.3
     ln Hash.3 Tcl_CreateHashEntry.3