Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XmtHashTableCreate(3)	   Library Functions Manual	 XmtHashTableCreate(3)

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

       #include	<Xmt/Hash.h>

       XmtHashTable XmtHashTableCreate(int size)

       void XmtHashTableDestroy(XmtHashTable table)

       void XmtHashTableStore(XmtHashTable table, XtPointer key, XtPointer

       Boolean XmtHashTableLookup(XmtHashTable table, XtPointer	key, XtPointer

       void XmtHashTableDelete(XmtHashTable table, XtPointer key)

       void XmtHashTableForEach(XmtHashTable table, XmtHashTableForEachProc
		      proc )

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


       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

       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.


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


       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.

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

       XmtHashTableCreate() creates and	returns	an XmtHashTable	size specifies
       the  base 2 logarithm of	the number of entries that should be pre-allo-
       cated 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 allo-
       cated memory have been stored in	the hash table,	those blocks of	memory
       must  be	 independently	freed;	you can	do this	with XmtHashTableForE-

       XmtHashTableStore() associates data with	key in hash  table  table  for
       later lookup with XmtHashTableLookup(). If there	was already data asso-
       ciated 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  XrmStringTo-
       Quark() 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.  Oth-
       erwise,	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.

       Chapter 8, Utility Functions.

Xmt				  Motif	Tools		 XmtHashTableCreate(3)


Want to link to this manual page? Use this URL:

home | help