NAME

SYNOPSIS

ARGUMENTS

size

For XmtHashTableCreate(), the log2 of the expected number of entries in the hash table. The hash table will be created with 2size entries preallocated.

table

The hash table that is to be manipulated.

key

An untyped value that identifies the data to be stored in the hash table, looked up in the hash table or deleted from the hash table.

data

For XmtHashTableStore(), an untyped value to be stored in the hash table.

proc

For XmtHashTableForEach(), a procedure that will be called for each item in the hash table.

OUTPUTS

data

For XmtHashTableLookup(), the address at which the data associated with the specified key will be stored.

RETURNS

XmtHashTableCreate() returns the newly created hash table.

XmtHashTableLookup() returns True if data was found for the specified key, and False if no data was associated with that key.

DESCRIPTION

XmtHashTableCreate() creates and returns an XmtHashTable size specifies the base 2 logarithm of the number of entries that should be pre-allocated in the table.

XmtHashTableDestroy() frees all storage associated with the XmtHashTable table. Once this function is called, table should never again be referenced. Note that this function does not free storage associated with the individual hash table entries. If pointers to allocated memory have been stored in the hash table, those blocks of memory must be independently freed; you can do this with XmtHashTableForEach().

XmtHashTableStore() associates data with key in hash table table for later lookup with XmtHashTableLookup(). If there was already data associated with key, it is overwritten with the new data.

Both key and data are untyped values with the same size as the untyped pointer XtPointer. The only restriction on values used as keys is that they be unique. Widget pointers are suitable as hash table keys since they are unique within a single process. Windows and other X IDs are not necessarily unique if an application connects to more than one X display. To use a string as a key, first convert it to a quark (a unique identifier for a string) with the Xlib function XrmStringToQuark() or XrmPermStringToQuark().

If the data you wish to store in the hash table is the same size or smaller than an XtPointer, then you can pass it directly as data. Otherwise, you should make sure that it is in static or allocated storage and pass a pointer to it as the data argument. Note that the hash table routines do not distinguish between these cases-data is simply treated as an untyped value. In particular, when you store pointers in a hash table, the table does not make a copy of the pointed-at storage, nor does it ever free that storage when the table is destroyed.

XmtHashTableLookup() looks up the data associated with key in table and stores it at the location specified by data. It returns True if data associated with key was found in the hash table, or False otherwise. Note that XmtHashTableLookup() simply looks up an untyped value with the same size as an XtPointer. The application may interpret this value as the data itself, or as a pointer to the data.

XmtHashTableDelete() removes any entry associated with the key key from the hash table table. If no entry associated with key exists in table, then XmtHashTableDelete() does nothing.

XmtHashTableForEach() calls the specified procedure, proc once for each key/value pair associated in the hash table table. proc is passed three arguments each time it is called: the hash table, the key, and the address of the data associated with the key.

XmtHashTableForEach() makes no guarantees about the order in which items will be enumerated. While enumerating the entries in a hash table, you must not take any actions that would change those entries. In particular, the procedure you specify must not delete entries or add new ones by calling XmtHashTableDelete() or XmtHashTableStore(). Since proc is passed the address of the data value associated with each key, it may safely modify the data value.

SEE ALSO