listhash/hash_new.3.in

   1 .TH @LISTHASH_PREFIX@_hash_new 3 "Jan 2000" "University of Illinois" "C Library Calls"
   2 \" @configure_input@
   3 .SH NAME
   4 @LISTHASH_PREFIX@_hash_new, @LISTHASH_PREFIX@_hash_free, @LISTHASH_PREFIX@_hash_next,
   5 @LISTHASH_PREFIX@_hash_prev, @LISTHASH_PREFIX@_hash_getkey, @LISTHASH_PREFIX@_hash_search,
   6 @LISTHASH_PREFIX@_hash_add, @LISTHASH_PREFIX@_hash_del \- hash table routines
   7 .SH SYNOPSIS
   8 .B #include <@LISTHASH_PREFIX@.h>
   9 .P
  10 .BI "@LISTHASH_PREFIX@_hash_t *@LISTHASH_PREFIX@_hash_new(int " num ", int (*" hashfunc ")());"
  11 .br
  12 .BI "void @LISTHASH_PREFIX@_hash_free(@LISTHASH_PREFIX@_hash_t *" h ", void (*" freefunc ")());"
  13 .br
  14 .BI "int @LISTHASH_PREFIX@_hash_next(@LISTHASH_PREFIX@_hash_t *" h ", @LISTHASH_PREFIX@_hashptr_t *" hp ");"
  15 .br
  16 .BI "int @LISTHASH_PREFIX@_hash_prev(@LISTHASH_PREFIX@_hash_t *" h ", @LISTHASH_PREFIX@_hashptr_t *" hp ");"
  17 .br
  18 .BI "int @LISTHASH_PREFIX@_hash_search(@LISTHASH_PREFIX@_hash_t *" h ", @LISTHASH_PREFIX@_hashptr_t *" hp ","
  19 .BI "void *" data ", int (*" matchfunc ")());"
  20 .br
  21 .BI "int @LISTHASH_PREFIX@_hash_getkey(@LISTHASH_PREFIX@_hash_t *" h ", @LISTHASH_PREFIX@_hashptr_t *" hp ","
  22 .BI "void *" data ", int (*" matchfunc ")());"
  23 .br
  24 .BI "int @LISTHASH_PREFIX@_hash_add(@LISTHASH_PREFIX@_hash_t *" h ", void *" data ");"
  25 .br
  26 .BI "int @LISTHASH_PREFIX@_hash_del(@LISTHASH_PREFIX@_hash_t *" h ", @LISTHASH_PREFIX@_hashptr_t *" hp ");"
  27 .SH DESCRIPTION
  28 The \fB@LISTHASH_PREFIX@_hash_new\fP() function creates a new hash with \fInum\fP
  29 buckets and using hash function pointed to by \fIhashfunc\fP.  If
  30 \fIhashfunc\fP is \fINULL\fP, a default hash function designed for
  31 7-bit ASCII strings is used.
  32
  33 The \fB@LISTHASH_PREFIX@_hash_free\fP() function deallocates all memory associated
  34 with the hash structure \fIh\fP.  If \fIfreefunc\fP is not \fINULL\fP,
  35 it is called to free memory associated with each node in the hash.
  36
  37 The \fB@LISTHASH_PREFIX@_hash_next\fP() and \fB@LISTHASH_PREFIX@_hash_prev\fP() functions are
  38 used to iterate through the hash.  The \fI@LISTHASH_PREFIX@_hashptr_t\fP structure
  39 has two fields: \fIbucket\fP, which indicates the current bucket in the
  40 hash, and \fInode\fP, which is a pointer to the current node in the current
  41 bucket.  To start at the beginning or end of the hash, the caller should
  42 initialize \fIhp.bucket\fP to \-1 and \fIhp.node\fP to \fINULL\fP.
  43
  44 The \fB@LISTHASH_PREFIX@_hash_search\fP() function searches iteratively through the
  45 hash \fIh\fP until it finds a node whose contents match \fIdata\fP using
  46 the matching function \fImatchfunc\fP.  Searching begins at the location
  47 pointed to by \fIhp\fP.
  48
  49 The \fB@LISTHASH_PREFIX@_hash_getkey\fP() function uses the hash function associated
  50 with \fIh\fP to determine which bucket \fIdata\fP should be in, and searches
  51 only that bucket for a matching node using \fImatchfunc\fP.  Searching
  52 begins at the location pointed to by \fIhp\fP.
  53
  54 The \fB@LISTHASH_PREFIX@_hash_add\fP() function adds \fIdata\fP into hash \fIh\fP.
  55
  56 The \fB@LISTHASH_PREFIX@_hash_del\fP() function removes the node referenced by
  57 \fIhp\fP.
  58 .SH RETURN VALUE
  59 The \fB@LISTHASH_PREFIX@_hash_new\fP() function returns a pointer to the new hash
  60 structure, or \fINULL\fP on error.
  61
  62 The \fB@LISTHASH_PREFIX@_hash_next\fP() and \fB@LISTHASH_PREFIX@_hash_prev\fP() functions
  63 return 1 when valid data is returned, and 0 at the end of the hash.
  64
  65 The \fB@LISTHASH_PREFIX@_hash_getkey\fP() and \fB@LISTHASH_PREFIX@_hash_search\fP() functions
  66 return 1 when a match is found, or 0 otherwise.
  67
  68 The \fB@LISTHASH_PREFIX@_hash_add\fP() function returns 0 on success, or \-1 on
  69 error (and sets \fIerrno\fP).
  70
  71 The \fB@LISTHASH_PREFIX@_hash_del\fP() function returns 0 on success, or \-1 on
  72 error (and sets \fIerrno\fP).
  73 .SH SEE ALSO
  74 .BR @LISTHASH_PREFIX@_list_new (3)