GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  XMTHASHTABLECREATE (3)

NAME

XmtHashTableCreate(), XmtHashTableDestroy(), XmtHashTableStore(), XmtHashTableLookup(), XmtHashTableDelete(), XmtHashTableForEach() - hash table functions.

CONTENTS

SYNOPSIS

   #include <Xmt/Hash.h>

   XmtHashTable XmtHashTableCreate(int size)

   void XmtHashTableDestroy(XmtHashTable table)

   void XmtHashTableStore(XmtHashTable table, XtPointer key, XtPointer data)

   Boolean XmtHashTableLookup(XmtHashTable table, XtPointer key, XtPointer *data)

   void XmtHashTableDelete(XmtHashTable table, XtPointer key)

   void XmtHashTableForEach(XmtHashTable table, XmtHashTableForEachProc proc )

   typedef void (*XmtHashTableForEachProc)(XmtHashTable table, XtPointer key, XtPointer *data);

ARGUMENTS

INPUTS
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

A hash table is a data structure that can efficiently associate arbitrary data with arbitrary keys. It is some times known as an associative array. These functions allow you to create and manipulate hash tables.

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

Chapter 8, Utility Functions.
Search for    or go to Top of page |  Section 3 |  Main Index


Xmt XMTHASHTABLECREATE (3) Motif Tools

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.