Named String Tables

This interface provides general purpose string hash tables. The hash tables are useful for saving and retrieving a string-keyed integer value, and for detecting or preventing the occurrence of duplicate strings in a list. The hash tables are persistent until explicitly freed, i.e., they remain in memory after a script completes (if not destroyed), and can be invoked by subsequent scripts. Each hash table is accessed by an arbitrary user-supplied name, and there is no limit on the number of tables that can be created.

(int) FindNameTable(tabname, create)
This function will create or verify the existence of a named string hash table. The named tables are available for use in scripts, for associating a string with an integer and for efficiently ensuring uniqueness in a collection of strings. The named tables persist until explicitly destroyed.

The tabname is an arbitrary name token used to access a named hash table. This function returns 1 if the named hash table exists, 0 otherwise. If the boolean argument create is nonzero, if the named table does not exist, it will be created, and 1 returned.

(int) RemoveNameTable(tabname)
This function will destroy a named hash table, as created with FindNameTable in create mode. It the table exists, it will be destroyed, and 1 is returned. If the given name does not match an existing table, 0 is returned.

(stringlist_handle) ListNameTables()
This function returns a handle to a list of names of named hash tables currently in memory.

(int) ClearNameTables()
This functions destroys all named hash tables in memory.

(int) AddNameToTable(tabname, name, value)
This will add a string and associated integer to a named hash table. The hash table whose name is given as the first argument must exist in memory, as created with FindNameTable in create mode. The name can be any non-null and non-empty string. The value can be any integer, however, the value -1 is reserved for internal use as a ``not in table'' indication.

If name is inserted into the table, 1 is returned. If name already exists in the table, or the table does not exist, 0 is returned. The value is ignored if the name already exists in the table, the existing value is not updated.

(int) RemoveNameFromTable(tabname, name)
This will remove the name string from the named hash table whose name is given as the first argument. If the name string is found and removed, 1 is returned. Otherwise, 0 is returned.

(int) FindNameInTable(tabname, name)
This function will return the data value saved with the name string in the table whose name is given as the first argument. If the table is not found, or the name string is not found, -1 is returned. Otherwise the returned value is that supplied to AddNameToTable for the name string. Note that it is a bad idea to use -1 as a data value.

(stringlist_handle) ListNamesInTable(tabname)
This function returns a handle to a list of the strings saved in the hash table whose name is supplied as the first argument.