From 02df2f52a70ba3e25aa1ceacb91ee2586a9431ac Mon Sep 17 00:00:00 2001 From: andreas_kupries Date: Thu, 18 Jan 2001 19:09:55 +0000 Subject: 2000-01-18 Andreas Kupries * 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'. FossilOrigin-Name: f44e486cdff1f9ea3453b7837b273cc123b86afe --- ChangeLog | 26 +++++++++++++++ doc/Hash.3 | 89 ++++++++++++++++++++++++++------------------------- generic/tcl.decls | 4 +-- generic/tcl.h | 9 ++++-- generic/tclDecls.h | 12 +++---- generic/tclHash.c | 12 +++---- generic/tclObj.c | 5 +-- generic/tclStubInit.c | 4 +-- unix/mkLinks | 4 +-- 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 + + * 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 * tests/winPipe.test (winpipe-1.20): @@ -19,6 +44,7 @@ [Bug 119416, Patch 102972] 2000-12-14 Don Porter + * 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 \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 -- cgit v0.12