libs/dbprim/doc/html/group__dbprim__smat.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
   3 <title>Sparse matrices</title>
   4 <link href="doxygen.css" rel="stylesheet" type="text/css">
   5 </head><body bgcolor="#ffffff">
   6 <!-- Generated by Doxygen 1.2.8.1 -->
   7 <center>
   8 <a class="qindex" href="index.html">Main Page</a> &nbsp; <a class="qindex" href="modules.html">Modules</a> &nbsp; </center>
   9 <hr><h1>Sparse matrices</h1>Operations for sparse matrices.
  10 <a href="#_details">More...</a><table border=0 cellpadding=0 cellspacing=0>
  11 <tr><td colspan=2><br><h2>Defines</h2></td></tr>
  12 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a21">SMAT_TABLE_INIT</a>(flags, resize, extra)</td></tr>
  13 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix table static initializer.</em> <a href="#a21">More...</a><em></em></font><br><br></td></tr>
  14 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a22">st_verify</a>(table)</td></tr>
  15 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix table verification macro.</em> <a href="#a22">More...</a><em></em></font><br><br></td></tr>
  16 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a23">st_flags</a>(table)</td></tr>
  17 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix table flags.</em> <a href="#a23">More...</a><em></em></font><br><br></td></tr>
  18 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a24">st_frozen</a>(table)</td></tr>
  19 <tr><td>&nbsp;</td><td><font size=-1><em>Determine if a sparse matrix is frozen.</em> <a href="#a24">More...</a><em></em></font><br><br></td></tr>
  20 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a25">st_modulus</a>(table)</td></tr>
  21 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix table modulus.</em> <a href="#a25">More...</a><em></em></font><br><br></td></tr>
  22 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a26">st_count</a>(table)</td></tr>
  23 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix table count.</em> <a href="#a26">More...</a><em></em></font><br><br></td></tr>
  24 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a27">st_extra</a>(table)</td></tr>
  25 <tr><td>&nbsp;</td><td><font size=-1><em>Extra pointer data in a sparse matrix table.</em> <a href="#a27">More...</a><em></em></font><br><br></td></tr>
  26 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a28">st_size</a>(table)</td></tr>
  27 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix table memory size.</em> <a href="#a28">More...</a><em></em></font><br><br></td></tr>
  28 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a29">SMAT_HEAD_INIT</a>(elem, object)</td></tr>
  29 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix list head static initializer.</em> <a href="#a29">More...</a><em></em></font><br><br></td></tr>
  30 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a30">sh_verify</a>(head)</td></tr>
  31 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix list head verification macro.</em> <a href="#a30">More...</a><em></em></font><br><br></td></tr>
  32 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a31">sh_elem</a>(head)</td></tr>
  33 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix list head element macro.</em> <a href="#a31">More...</a><em></em></font><br><br></td></tr>
  34 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a32">sh_table</a>(head)</td></tr>
  35 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix list head table pointer.</em> <a href="#a32">More...</a><em></em></font><br><br></td></tr>
  36 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a33">sh_frozen</a>(head)</td></tr>
  37 <tr><td>&nbsp;</td><td><font size=-1><em>Determine if a sparse matrix is frozen.</em> <a href="#a33">More...</a><em></em></font><br><br></td></tr>
  38 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a34">sh_count</a>(head)</td></tr>
  39 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix list count.</em> <a href="#a34">More...</a><em></em></font><br><br></td></tr>
  40 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a35">sh_first</a>(head)</td></tr>
  41 <tr><td>&nbsp;</td><td><font size=-1><em>First element in sparse matrix list.</em> <a href="#a35">More...</a><em></em></font><br><br></td></tr>
  42 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a36">sh_last</a>(head)</td></tr>
  43 <tr><td>&nbsp;</td><td><font size=-1><em>Last element in sparse matrix list.</em> <a href="#a36">More...</a><em></em></font><br><br></td></tr>
  44 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a37">sh_object</a>(head)</td></tr>
  45 <tr><td>&nbsp;</td><td><font size=-1><em>Object represented by a sparse matrix list head.</em> <a href="#a37">More...</a><em></em></font><br><br></td></tr>
  46 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a38">sh_size</a>(head)</td></tr>
  47 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix list memory size.</em> <a href="#a38">More...</a><em></em></font><br><br></td></tr>
  48 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a39">se_verify</a>(entry)</td></tr>
  49 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix entry verification macro.</em> <a href="#a39">More...</a><em></em></font><br><br></td></tr>
  50 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a40">se_table</a>(entry)</td></tr>
  51 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix entry table.</em> <a href="#a40">More...</a><em></em></font><br><br></td></tr>
  52 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a41">_se_link</a>(entry)</td></tr>
  53 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix entry linked list element.</em> <a href="#a41">More...</a><em></em></font><br><br></td></tr>
  54 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a42">se_flags</a>(entry)</td></tr>
  55 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix entry flags.</em> <a href="#a42">More...</a><em></em></font><br><br></td></tr>
  56 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a43">se_hash</a>(entry)</td></tr>
  57 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix table entry hash value.</em> <a href="#a43">More...</a><em></em></font><br><br></td></tr>
  58 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a44">se_next</a>(entry, n)</td></tr>
  59 <tr><td>&nbsp;</td><td><font size=-1><em>Next element in sparse matrix list.</em> <a href="#a44">More...</a><em></em></font><br><br></td></tr>
  60 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a45">se_prev</a>(entry, n)</td></tr>
  61 <tr><td>&nbsp;</td><td><font size=-1><em>Previous element in sparse matrix list.</em> <a href="#a45">More...</a><em></em></font><br><br></td></tr>
  62 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a46">se_lflags</a>(entry, n)</td></tr>
  63 <tr><td>&nbsp;</td><td><font size=-1><em>Flags associated with an entry in a sparse matrix list.</em> <a href="#a46">More...</a><em></em></font><br><br></td></tr>
  64 <tr><td nowrap align=right valign=top>#define&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a47">se_object</a>(entry, n)</td></tr>
  65 <tr><td>&nbsp;</td><td><font size=-1><em>Object associated with an entry in a sparse matrix list.</em> <a href="#a47">More...</a><em></em></font><br><br></td></tr>
  66 <tr><td colspan=2><br><h2>Typedefs</h2></td></tr>
  67 <tr><td nowrap align=right valign=top>typedef struct _smat_table_s&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a></td></tr>
  68 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix table.</em> <a href="#a0">More...</a><em></em></font><br><br></td></tr>
  69 <tr><td nowrap align=right valign=top>typedef struct _smat_head_s&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a></td></tr>
  70 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix list head.</em> <a href="#a1">More...</a><em></em></font><br><br></td></tr>
  71 <tr><td nowrap align=right valign=top>typedef struct _smat_entry_s&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a></td></tr>
  72 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix entry.</em> <a href="#a2">More...</a><em></em></font><br><br></td></tr>
  73 <tr><td nowrap align=right valign=top>typedef unsigned long (*&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a3">smat_resize_t</a> )(<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *, unsigned long)</td></tr>
  74 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix table resize callback.</em> <a href="#a3">More...</a><em></em></font><br><br></td></tr>
  75 <tr><td nowrap align=right valign=top>typedef unsigned long (*&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> )(<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *, void *)</td></tr>
  76 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix iteration callback.</em> <a href="#a4">More...</a><em></em></font><br><br></td></tr>
  77 <tr><td nowrap align=right valign=top>typedef unsigned long (*&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a5">smat_comp_t</a> )(<a class="el" href="group__dbprim__key.html#a0">db_key_t</a> *, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *)</td></tr>
  78 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix comparison callback.</em> <a href="#a5">More...</a><em></em></font><br><br></td></tr>
  79 <tr><td nowrap align=right valign=top>typedef enum <a class="el" href="group__dbprim__smat.html#a48">_smat_loc_e</a>&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a6">smat_loc_t</a></td></tr>
  80 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix location.</em> <a href="#a6">More...</a><em></em></font><br><br></td></tr>
  81 <tr><td colspan=2><br><h2>Enumerations</h2></td></tr>
  82 <tr><td nowrap align=right valign=top>enum &nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a48">_smat_loc_e</a> { <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a>,
  83 <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a>
  84  }</td></tr>
  85 <tr><td>&nbsp;</td><td><font size=-1><em>Sparse matrix location.</em> <a href="#a48">More...</a><em></em></font><br><br></td></tr>
  86 <tr><td colspan=2><br><h2>Functions</h2></td></tr>
  87 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a7">smat_cleanup</a> (void)</td></tr>
  88 <tr><td>&nbsp;</td><td><font size=-1><em>Clean up the smat free list.</em> <a href="#a7">More...</a><em></em></font><br><br></td></tr>
  89 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a8">smat_freemem</a> (void)</td></tr>
  90 <tr><td>&nbsp;</td><td><font size=-1><em>Report how much memory is used by the free list.</em> <a href="#a8">More...</a><em></em></font><br><br></td></tr>
  91 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a9">st_init</a> (<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *table, unsigned long flags, <a class="el" href="group__dbprim__smat.html#a3">smat_resize_t</a> resize, void *extra, unsigned long init_mod)</td></tr>
  92 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a10">st_add</a> (<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *table, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> **entry_p, <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> *head1, <a class="el" href="group__dbprim__link.html#a4">link_loc_t</a> loc1, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *ent1, <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> *head2, <a class="el" href="group__dbprim__link.html#a4">link_loc_t</a> loc2, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *ent2)</td></tr>
  93 <tr><td>&nbsp;</td><td><font size=-1><em>Add an entry to a sparse matrix.</em> <a href="#a10">More...</a><em></em></font><br><br></td></tr>
  94 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a11">st_remove</a> (<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *table, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *entry)</td></tr>
  95 <tr><td>&nbsp;</td><td><font size=-1><em>Remove an entry from a sparse matrix.</em> <a href="#a11">More...</a><em></em></font><br><br></td></tr>
  96 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a12">st_find</a> (<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *table, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> **entry_p, <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> *head1, <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> *head2)</td></tr>
  97 <tr><td>&nbsp;</td><td><font size=-1><em>Find an entry in a sparse matrix.</em> <a href="#a12">More...</a><em></em></font><br><br></td></tr>
  98 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a13">st_iter</a> (<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *table, <a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> iter_func, void *extra)</td></tr>
  99 <tr><td>&nbsp;</td><td><font size=-1><em>Iterate over each entry in a sparse matrix.</em> <a href="#a13">More...</a><em></em></font><br><br></td></tr>
 100 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a14">st_flush</a> (<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *table, <a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> flush_func, void *extra)</td></tr>
 101 <tr><td>&nbsp;</td><td><font size=-1><em>Flush a sparse matrix.</em> <a href="#a14">More...</a><em></em></font><br><br></td></tr>
 102 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a15">st_resize</a> (<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *table, unsigned long new_size)</td></tr>
 103 <tr><td>&nbsp;</td><td><font size=-1><em>Resize a sparse matrix table.</em> <a href="#a15">More...</a><em></em></font><br><br></td></tr>
 104 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a16">st_free</a> (<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *table)</td></tr>
 105 <tr><td>&nbsp;</td><td><font size=-1><em>Free memory used by an empty sparse matrix table.</em> <a href="#a16">More...</a><em></em></font><br><br></td></tr>
 106 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a17">sh_init</a> (<a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> *head, <a class="el" href="group__dbprim__smat.html#a6">smat_loc_t</a> elem, void *object)</td></tr>
 107 <tr><td>&nbsp;</td><td><font size=-1><em>Dynamically initialize a sparse matrix row or column head.</em> <a href="#a17">More...</a><em></em></font><br><br></td></tr>
 108 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a18">sh_move</a> (<a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> *head, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *elem, <a class="el" href="group__dbprim__link.html#a4">link_loc_t</a> loc, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *elem2)</td></tr>
 109 <tr><td>&nbsp;</td><td><font size=-1><em>Move an entry within a row or column list.</em> <a href="#a18">More...</a><em></em></font><br><br></td></tr>
 110 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a19">sh_find</a> (<a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> *head, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> **elem_p, <a class="el" href="group__dbprim__smat.html#a5">smat_comp_t</a> comp_func, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *start, <a class="el" href="group__dbprim__key.html#a0">db_key_t</a> *key)</td></tr>
 111 <tr><td>&nbsp;</td><td><font size=-1><em>Find an entry in a row or column of a sparse matrix.</em> <a href="#a19">More...</a><em></em></font><br><br></td></tr>
 112 <tr><td nowrap align=right valign=top>unsigned long&nbsp;</td><td valign=bottom><a class="el" href="group__dbprim__smat.html#a20">sh_iter</a> (<a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> *head, <a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> iter_func, void *extra)</td></tr>
 113 <tr><td>&nbsp;</td><td><font size=-1><em>Iterate over each entry in a row or column of a sparse matrix.</em> <a href="#a20">More...</a><em></em></font><br><br></td></tr>
 114 </table>
 115 <hr><a name="_details"></a><h2>Detailed Description</h2>
 116 Sparse matrices are advanced data structures used to represent associations. For instance, a manager may have several employees, but several of those employees may report to more than one manager. (Yes, this is a contrived example, so sue me.) The simplest way to represent such assocations is with a matrix, or a two-dimensional array. However, such an implementation cannot easily be extended dynamically--imagine if a manager retires and two more are hired, for instance. It would also use an enormous amount of memory, as most employees would only report to one or two managers.
 117 <p>
 118 A sparse matrix solves this problem by only allocating memory for the cells in the full matrix which are actually used. That is, no memory is allocated to represent Alice reporting to Bob unless Alice actually does report to Bob. This is a simple concept, but fairly difficult to implement efficiently--how do you tell if Alice reports to Bob? The solution utilized by this library is to combine the strengths of linked lists and hash tables. Each cell is in two linked lists, rooted at the rows and columns of the matrix, but a hash table is used when attempting to look up a given cell. If the cell is allocated, then there will be an entry in the hash table, and finding the given cell is as fast as a hash table look-up.
 119 <p>
 120 Because sparse matrices are so complicated, there are three structures and a variety of operations used. Two of the structures, <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> and <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>, are caller-allocated. However, the third structure, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>, must be allocated by the library. To avoid too much overhead from malloc(), a free list is used. The free list may be managed with the <a class="el" href="group__dbprim__smat.html#a7">smat_cleanup</a>() and <a class="el" href="group__dbprim__smat.html#a8">smat_freemem</a>() calls.
 121 <p>
 122 The <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> contains the hash table. Only one of these need be allocated per type of association--for instance, in the above example, only one <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> needs to be allocated to represent the manager-employee relationship.
 123 <p>
 124 The <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> contains the linked list. There are actually two kinds of these structures--one is <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a>, which could be regarded as a ``row,'' and the other is <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a>, which could be regarded as a ``column.'' Which one is used for which type of data is irrelevant, as long as consistency is maintained. For the above example, a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> for a manager may be <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a>, and one for an employee must then be <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a>. (These values are set when initializing the <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> structure.)
 125 <p>
 126 An association may be created with the <a class="el" href="group__dbprim__smat.html#a10">st_add</a>() function, which allows an arbitrary ordering in the associated linked lists by the same mechanism as for the linked list component of the library. An association may be removed with <a class="el" href="group__dbprim__smat.html#a11">st_remove</a>(), or looked up with <a class="el" href="group__dbprim__smat.html#a12">st_find</a>(). If iteration over all associations is desired, use the <a class="el" href="group__dbprim__smat.html#a13">st_iter</a>() function. Removing all associations from a table may be performed with <a class="el" href="group__dbprim__smat.html#a14">st_flush</a>(), which optionally calls a user-defined clean-up function. The associated hash table may be resized with <a class="el" href="group__dbprim__smat.html#a15">st_resize</a>(), and the bucket table may be released with <a class="el" href="group__dbprim__smat.html#a16">st_free</a>().
 127 <p>
 128 An association may also be reordered within the linked lists using the <a class="el" href="group__dbprim__smat.html#a18">sh_move</a>() function. If a particular entry is desired, use the <a class="el" href="group__dbprim__smat.html#a19">sh_find</a>() function with a user-defined comparison function to locate it. Iteration may be performed with the <a class="el" href="group__dbprim__smat.html#a20">sh_iter</a>() function, and all entries in a given linked list may be removed with the sh_flush() function, which again may optionally call a user-defined clean-up function. <hr><h2>Define Documentation</h2>
 129 <a name="a29" doxytag="dbprim.h.top::SMAT_HEAD_INIT"></a><p>
 130 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 131   <tr>
 132     <td class="md">
 133       <table cellpadding="0" cellspacing="0" border="0">
 134         <tr>
 135           <td nowrap valign="top"><b>
 136 #define SMAT_HEAD_INIT(
 137           </b></td>
 138           <td valign="bottom"><b>
 139 elem, object&nbsp;)
 140       </table>
 141     </td>
 142   </tr>
 143 </table>
 144 <table cellspacing=5 cellpadding=0 border=0>
 145   <tr>
 146     <td>
 147       &nbsp;
 148     </td>
 149     <td>
 150
 151 <p>
 152
 153 <p>
 154  This macro statically initializes a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.<dl compact><dt>
 155 <b>Parameters: </b><dd>
 156 <table border=0 cellspacing=2 cellpadding=0>
 157 <tr><td valign=top><em>elem</em>
 158 &nbsp;</td><td>
 159 One of <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a> or <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a> specifing whether the object is a member of the set of rows or columns. </td></tr>
 160 <tr><td valign=top><em>object</em>
 161 &nbsp;</td><td>
 162 A pointer to <code>void</code> representing the object associated with the list head. </td></tr>
 163 </table>
 164 </dl>    </td>
 165   </tr>
 166 </table>
 167 <a name="a21" doxytag="dbprim.h.top::SMAT_TABLE_INIT"></a><p>
 168 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 169   <tr>
 170     <td class="md">
 171       <table cellpadding="0" cellspacing="0" border="0">
 172         <tr>
 173           <td nowrap valign="top"><b>
 174 #define SMAT_TABLE_INIT(
 175           </b></td>
 176           <td valign="bottom"><b>
 177 flags, resize, extra&nbsp;)
 178       </table>
 179     </td>
 180   </tr>
 181 </table>
 182 <table cellspacing=5 cellpadding=0 border=0>
 183   <tr>
 184     <td>
 185       &nbsp;
 186     </td>
 187     <td>
 188
 189 <p>
 190
 191 <p>
 192  This macro statically initializes a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>.<dl compact><dt>
 193 <b>Parameters: </b><dd>
 194 <table border=0 cellspacing=2 cellpadding=0>
 195 <tr><td valign=top><em>flags</em>
 196 &nbsp;</td><td>
 197 A bit-wise OR of <a class="el" href="group__dbprim__hash.html#a16">HASH_FLAG_AUTOGROW</a> and <a class="el" href="group__dbprim__hash.html#a17">HASH_FLAG_AUTOSHRINK</a>. If neither behavior is desired, use 0. </td></tr>
 198 <tr><td valign=top><em>resize</em>
 199 &nbsp;</td><td>
 200 A <a class="el" href="group__dbprim__smat.html#a3">smat_resize_t</a> function pointer for determining whether resizing is permitted and/or for notification of the resize. </td></tr>
 201 <tr><td valign=top><em>extra</em>
 202 &nbsp;</td><td>
 203 Extra pointer data that should be associated with the sparse matrix. </td></tr>
 204 </table>
 205 </dl>    </td>
 206   </tr>
 207 </table>
 208 <a name="a41" doxytag="dbprim.h.top::_se_link"></a><p>
 209 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 210   <tr>
 211     <td class="md">
 212       <table cellpadding="0" cellspacing="0" border="0">
 213         <tr>
 214           <td nowrap valign="top"><b>
 215 #define _se_link(
 216           </b></td>
 217           <td valign="bottom"><b>
 218 entry&nbsp;)
 219       </table>
 220     </td>
 221   </tr>
 222 </table>
 223 <table cellspacing=5 cellpadding=0 border=0>
 224   <tr>
 225     <td>
 226       &nbsp;
 227     </td>
 228     <td>
 229
 230 <p>
 231
 232 <p>
 233 For internal use only.    </td>
 234   </tr>
 235 </table>
 236 <a name="a42" doxytag="dbprim.h.top::se_flags"></a><p>
 237 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 238   <tr>
 239     <td class="md">
 240       <table cellpadding="0" cellspacing="0" border="0">
 241         <tr>
 242           <td nowrap valign="top"><b>
 243 #define se_flags(
 244           </b></td>
 245           <td valign="bottom"><b>
 246 entry&nbsp;)
 247       </table>
 248     </td>
 249   </tr>
 250 </table>
 251 <table cellspacing=5 cellpadding=0 border=0>
 252   <tr>
 253     <td>
 254       &nbsp;
 255     </td>
 256     <td>
 257
 258 <p>
 259
 260 <p>
 261  This macro retrieves a set of user-defined flags associated with the entry. It may be used as an lvalue to set those flags.<dl compact><dt>
 262 <b>Parameters: </b><dd>
 263 <table border=0 cellspacing=2 cellpadding=0>
 264 <tr><td valign=top><em>entry</em>
 265 &nbsp;</td><td>
 266 A pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>.
 267 <p>
 268 </td></tr>
 269 </table>
 270 </dl><dl compact><dt>
 271 <b>Returns: </b><dd>
 272 An <code>unsigned long</code> containing the flags associated with the entry. </dl>    </td>
 273   </tr>
 274 </table>
 275 <a name="a43" doxytag="dbprim.h.top::se_hash"></a><p>
 276 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 277   <tr>
 278     <td class="md">
 279       <table cellpadding="0" cellspacing="0" border="0">
 280         <tr>
 281           <td nowrap valign="top"><b>
 282 #define se_hash(
 283           </b></td>
 284           <td valign="bottom"><b>
 285 entry&nbsp;)
 286       </table>
 287     </td>
 288   </tr>
 289 </table>
 290 <table cellspacing=5 cellpadding=0 border=0>
 291   <tr>
 292     <td>
 293       &nbsp;
 294     </td>
 295     <td>
 296
 297 <p>
 298
 299 <p>
 300  This macro retrieves the hash value of the given sparse matrix entry. If the sparse matrix hash been resized, this value may not be the same as a previous value.<dl compact><dt>
 301 <b>Parameters: </b><dd>
 302 <table border=0 cellspacing=2 cellpadding=0>
 303 <tr><td valign=top><em>entry</em>
 304 &nbsp;</td><td>
 305 A pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>.
 306 <p>
 307 </td></tr>
 308 </table>
 309 </dl><dl compact><dt>
 310 <b>Returns: </b><dd>
 311 An <code>unsigned long</code> containing the hash code for the entry. </dl>    </td>
 312   </tr>
 313 </table>
 314 <a name="a46" doxytag="dbprim.h.top::se_lflags"></a><p>
 315 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 316   <tr>
 317     <td class="md">
 318       <table cellpadding="0" cellspacing="0" border="0">
 319         <tr>
 320           <td nowrap valign="top"><b>
 321 #define se_lflags(
 322           </b></td>
 323           <td valign="bottom"><b>
 324 entry, n&nbsp;)
 325       </table>
 326     </td>
 327   </tr>
 328 </table>
 329 <table cellspacing=5 cellpadding=0 border=0>
 330   <tr>
 331     <td>
 332       &nbsp;
 333     </td>
 334     <td>
 335
 336 <p>
 337
 338 <p>
 339  This macro retrieves a set of user-defined flags associated with the entry in a sparse matrix list. It may be used as an lvalue to set those flags.<dl compact><dt>
 340 <b>Parameters: </b><dd>
 341 <table border=0 cellspacing=2 cellpadding=0>
 342 <tr><td valign=top><em>entry</em>
 343 &nbsp;</td><td>
 344 A pointer to <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. </td></tr>
 345 <tr><td valign=top><em>n</em>
 346 &nbsp;</td><td>
 347 One of <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a> or <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a> to specify which list thread is desired.
 348 <p>
 349 </td></tr>
 350 </table>
 351 </dl><dl compact><dt>
 352 <b>Returns: </b><dd>
 353 An <code>unsigned long</code> containing the flags associated with the entry. </dl>    </td>
 354   </tr>
 355 </table>
 356 <a name="a44" doxytag="dbprim.h.top::se_next"></a><p>
 357 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 358   <tr>
 359     <td class="md">
 360       <table cellpadding="0" cellspacing="0" border="0">
 361         <tr>
 362           <td nowrap valign="top"><b>
 363 #define se_next(
 364           </b></td>
 365           <td valign="bottom"><b>
 366 entry, n&nbsp;)
 367       </table>
 368     </td>
 369   </tr>
 370 </table>
 371 <table cellspacing=5 cellpadding=0 border=0>
 372   <tr>
 373     <td>
 374       &nbsp;
 375     </td>
 376     <td>
 377
 378 <p>
 379
 380 <p>
 381  This macro retrieves a pointer to the <a class="el" href="group__dbprim__link.html#a1">link_elem_t</a> for the next element in the sparse matrix list.
 382 <p>
 383 <dl compact><dt>
 384 <b>Warning: </b><dd>
 385 This macro may evaluate the <code>entry</code> and <code>n</code> arguments twice.</dl><dl compact><dt>
 386 <b>Parameters: </b><dd>
 387 <table border=0 cellspacing=2 cellpadding=0>
 388 <tr><td valign=top><em>entry</em>
 389 &nbsp;</td><td>
 390 A pointer to <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. </td></tr>
 391 <tr><td valign=top><em>n</em>
 392 &nbsp;</td><td>
 393 One of <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a> or <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a> to specify which list thread is desired.
 394 <p>
 395 </td></tr>
 396 </table>
 397 </dl><dl compact><dt>
 398 <b>Returns: </b><dd>
 399 A pointer to <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. </dl>    </td>
 400   </tr>
 401 </table>
 402 <a name="a47" doxytag="dbprim.h.top::se_object"></a><p>
 403 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 404   <tr>
 405     <td class="md">
 406       <table cellpadding="0" cellspacing="0" border="0">
 407         <tr>
 408           <td nowrap valign="top"><b>
 409 #define se_object(
 410           </b></td>
 411           <td valign="bottom"><b>
 412 entry, n&nbsp;)
 413       </table>
 414     </td>
 415   </tr>
 416 </table>
 417 <table cellspacing=5 cellpadding=0 border=0>
 418   <tr>
 419     <td>
 420       &nbsp;
 421     </td>
 422     <td>
 423
 424 <p>
 425
 426 <p>
 427  This macro retrieves a pointer to one of the object represented by the entry. It may be used as an lvalue to change the object pointed to. Care should be taken when using this feature.<dl compact><dt>
 428 <b>Parameters: </b><dd>
 429 <table border=0 cellspacing=2 cellpadding=0>
 430 <tr><td valign=top><em>entry</em>
 431 &nbsp;</td><td>
 432 A pointer to <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. </td></tr>
 433 <tr><td valign=top><em>n</em>
 434 &nbsp;</td><td>
 435 One of <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a> or <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a> to specify which list thread is desired.
 436 <p>
 437 </td></tr>
 438 </table>
 439 </dl><dl compact><dt>
 440 <b>Returns: </b><dd>
 441 A pointer to <code>void</code> representing the object. </dl>    </td>
 442   </tr>
 443 </table>
 444 <a name="a45" doxytag="dbprim.h.top::se_prev"></a><p>
 445 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 446   <tr>
 447     <td class="md">
 448       <table cellpadding="0" cellspacing="0" border="0">
 449         <tr>
 450           <td nowrap valign="top"><b>
 451 #define se_prev(
 452           </b></td>
 453           <td valign="bottom"><b>
 454 entry, n&nbsp;)
 455       </table>
 456     </td>
 457   </tr>
 458 </table>
 459 <table cellspacing=5 cellpadding=0 border=0>
 460   <tr>
 461     <td>
 462       &nbsp;
 463     </td>
 464     <td>
 465
 466 <p>
 467
 468 <p>
 469  This macro retrieves a pointer to the <a class="el" href="group__dbprim__link.html#a1">link_elem_t</a> for the previous element in the sparse matrix list.
 470 <p>
 471 <dl compact><dt>
 472 <b>Warning: </b><dd>
 473 This macro may evaluate the <code>entry</code> and <code>n</code> arguments twice.</dl><dl compact><dt>
 474 <b>Parameters: </b><dd>
 475 <table border=0 cellspacing=2 cellpadding=0>
 476 <tr><td valign=top><em>entry</em>
 477 &nbsp;</td><td>
 478 A pointer to <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. </td></tr>
 479 <tr><td valign=top><em>n</em>
 480 &nbsp;</td><td>
 481 One of <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a> or <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a> to specify which list thread is desired.
 482 <p>
 483 </td></tr>
 484 </table>
 485 </dl><dl compact><dt>
 486 <b>Returns: </b><dd>
 487 A pointer to <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. </dl>    </td>
 488   </tr>
 489 </table>
 490 <a name="a40" doxytag="dbprim.h.top::se_table"></a><p>
 491 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 492   <tr>
 493     <td class="md">
 494       <table cellpadding="0" cellspacing="0" border="0">
 495         <tr>
 496           <td nowrap valign="top"><b>
 497 #define se_table(
 498           </b></td>
 499           <td valign="bottom"><b>
 500 entry&nbsp;)
 501       </table>
 502     </td>
 503   </tr>
 504 </table>
 505 <table cellspacing=5 cellpadding=0 border=0>
 506   <tr>
 507     <td>
 508       &nbsp;
 509     </td>
 510     <td>
 511
 512 <p>
 513
 514 <p>
 515  This macro retrieves a pointer to the table that the sparse matrix entry is in.<dl compact><dt>
 516 <b>Parameters: </b><dd>
 517 <table border=0 cellspacing=2 cellpadding=0>
 518 <tr><td valign=top><em>entry</em>
 519 &nbsp;</td><td>
 520 A pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>.
 521 <p>
 522 </td></tr>
 523 </table>
 524 </dl><dl compact><dt>
 525 <b>Returns: </b><dd>
 526 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>. </dl>    </td>
 527   </tr>
 528 </table>
 529 <a name="a39" doxytag="dbprim.h.top::se_verify"></a><p>
 530 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 531   <tr>
 532     <td class="md">
 533       <table cellpadding="0" cellspacing="0" border="0">
 534         <tr>
 535           <td nowrap valign="top"><b>
 536 #define se_verify(
 537           </b></td>
 538           <td valign="bottom"><b>
 539 entry&nbsp;)
 540       </table>
 541     </td>
 542   </tr>
 543 </table>
 544 <table cellspacing=5 cellpadding=0 border=0>
 545   <tr>
 546     <td>
 547       &nbsp;
 548     </td>
 549     <td>
 550
 551 <p>
 552
 553 <p>
 554  This macro verifies that a given pointer actually does point to a sparse matrix entry.<dl compact><dt>
 555 <b>Parameters: </b><dd>
 556 <table border=0 cellspacing=2 cellpadding=0>
 557 <tr><td valign=top><em>entry</em>
 558 &nbsp;</td><td>
 559 A pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>.
 560 <p>
 561 </td></tr>
 562 </table>
 563 </dl><dl compact><dt>
 564 <b>Returns: </b><dd>
 565 Boolean true if <code>entry</code> is a valid sparse matrix entry or false otherwise. </dl>    </td>
 566   </tr>
 567 </table>
 568 <a name="a34" doxytag="dbprim.h.top::sh_count"></a><p>
 569 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 570   <tr>
 571     <td class="md">
 572       <table cellpadding="0" cellspacing="0" border="0">
 573         <tr>
 574           <td nowrap valign="top"><b>
 575 #define sh_count(
 576           </b></td>
 577           <td valign="bottom"><b>
 578 head&nbsp;)
 579       </table>
 580     </td>
 581   </tr>
 582 </table>
 583 <table cellspacing=5 cellpadding=0 border=0>
 584   <tr>
 585     <td>
 586       &nbsp;
 587     </td>
 588     <td>
 589
 590 <p>
 591
 592 <p>
 593  This macro retrieves the number of elements in the sparse matrix list rooted at <code>head</code>.<dl compact><dt>
 594 <b>Parameters: </b><dd>
 595 <table border=0 cellspacing=2 cellpadding=0>
 596 <tr><td valign=top><em>head</em>
 597 &nbsp;</td><td>
 598 A pointer to <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.
 599 <p>
 600 </td></tr>
 601 </table>
 602 </dl><dl compact><dt>
 603 <b>Returns: </b><dd>
 604 An <code>unsigned long</code> containing a count of the number of elements in the sparse matrix list. </dl>    </td>
 605   </tr>
 606 </table>
 607 <a name="a31" doxytag="dbprim.h.top::sh_elem"></a><p>
 608 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 609   <tr>
 610     <td class="md">
 611       <table cellpadding="0" cellspacing="0" border="0">
 612         <tr>
 613           <td nowrap valign="top"><b>
 614 #define sh_elem(
 615           </b></td>
 616           <td valign="bottom"><b>
 617 head&nbsp;)
 618       </table>
 619     </td>
 620   </tr>
 621 </table>
 622 <table cellspacing=5 cellpadding=0 border=0>
 623   <tr>
 624     <td>
 625       &nbsp;
 626     </td>
 627     <td>
 628
 629 <p>
 630
 631 <p>
 632  This macro retrieves the position indicator for the sparse matrix head. It will return one of <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a> or <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a>.<dl compact><dt>
 633 <b>Parameters: </b><dd>
 634 <table border=0 cellspacing=2 cellpadding=0>
 635 <tr><td valign=top><em>head</em>
 636 &nbsp;</td><td>
 637 A pointer to <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.
 638 <p>
 639 </td></tr>
 640 </table>
 641 </dl><dl compact><dt>
 642 <b>Returns: </b><dd>
 643 An <a class="el" href="group__dbprim__smat.html#a6">smat_loc_t</a>. </dl>    </td>
 644   </tr>
 645 </table>
 646 <a name="a35" doxytag="dbprim.h.top::sh_first"></a><p>
 647 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 648   <tr>
 649     <td class="md">
 650       <table cellpadding="0" cellspacing="0" border="0">
 651         <tr>
 652           <td nowrap valign="top"><b>
 653 #define sh_first(
 654           </b></td>
 655           <td valign="bottom"><b>
 656 head&nbsp;)
 657       </table>
 658     </td>
 659   </tr>
 660 </table>
 661 <table cellspacing=5 cellpadding=0 border=0>
 662   <tr>
 663     <td>
 664       &nbsp;
 665     </td>
 666     <td>
 667
 668 <p>
 669
 670 <p>
 671  This macro retrieves a pointer to the <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> for the first element in the sparse matrix list.
 672 <p>
 673 <dl compact><dt>
 674 <b>Warning: </b><dd>
 675 This macro may evaluate the <code>head</code> argument twice.</dl><dl compact><dt>
 676 <b>Parameters: </b><dd>
 677 <table border=0 cellspacing=2 cellpadding=0>
 678 <tr><td valign=top><em>head</em>
 679 &nbsp;</td><td>
 680 A pointer to <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.
 681 <p>
 682 </td></tr>
 683 </table>
 684 </dl><dl compact><dt>
 685 <b>Returns: </b><dd>
 686 A pointer to <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. </dl>    </td>
 687   </tr>
 688 </table>
 689 <a name="a33" doxytag="dbprim.h.top::sh_frozen"></a><p>
 690 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 691   <tr>
 692     <td class="md">
 693       <table cellpadding="0" cellspacing="0" border="0">
 694         <tr>
 695           <td nowrap valign="top"><b>
 696 #define sh_frozen(
 697           </b></td>
 698           <td valign="bottom"><b>
 699 head&nbsp;)
 700       </table>
 701     </td>
 702   </tr>
 703 </table>
 704 <table cellspacing=5 cellpadding=0 border=0>
 705   <tr>
 706     <td>
 707       &nbsp;
 708     </td>
 709     <td>
 710
 711 <p>
 712
 713 <p>
 714  This macro returns a non-zero value if the matrix is currently frozen. The sparse matrix may be frozen if there is an iteration in progress.<dl compact><dt>
 715 <b>Parameters: </b><dd>
 716 <table border=0 cellspacing=2 cellpadding=0>
 717 <tr><td valign=top><em>head</em>
 718 &nbsp;</td><td>
 719 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.
 720 <p>
 721 </td></tr>
 722 </table>
 723 </dl><dl compact><dt>
 724 <b>Returns: </b><dd>
 725 A zero value if the matrix is not frozen or a non-zero value if the matrix is frozen. </dl>    </td>
 726   </tr>
 727 </table>
 728 <a name="a36" doxytag="dbprim.h.top::sh_last"></a><p>
 729 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 730   <tr>
 731     <td class="md">
 732       <table cellpadding="0" cellspacing="0" border="0">
 733         <tr>
 734           <td nowrap valign="top"><b>
 735 #define sh_last(
 736           </b></td>
 737           <td valign="bottom"><b>
 738 head&nbsp;)
 739       </table>
 740     </td>
 741   </tr>
 742 </table>
 743 <table cellspacing=5 cellpadding=0 border=0>
 744   <tr>
 745     <td>
 746       &nbsp;
 747     </td>
 748     <td>
 749
 750 <p>
 751
 752 <p>
 753  This macro retrieves a pointer to the <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> for the last element in the sparse matrix list.
 754 <p>
 755 <dl compact><dt>
 756 <b>Warning: </b><dd>
 757 This macro may evaluate the <code>head</code> argument twice.</dl><dl compact><dt>
 758 <b>Parameters: </b><dd>
 759 <table border=0 cellspacing=2 cellpadding=0>
 760 <tr><td valign=top><em>head</em>
 761 &nbsp;</td><td>
 762 A pointer to <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.
 763 <p>
 764 </td></tr>
 765 </table>
 766 </dl><dl compact><dt>
 767 <b>Returns: </b><dd>
 768 A pointer to <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. </dl>    </td>
 769   </tr>
 770 </table>
 771 <a name="a37" doxytag="dbprim.h.top::sh_object"></a><p>
 772 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 773   <tr>
 774     <td class="md">
 775       <table cellpadding="0" cellspacing="0" border="0">
 776         <tr>
 777           <td nowrap valign="top"><b>
 778 #define sh_object(
 779           </b></td>
 780           <td valign="bottom"><b>
 781 head&nbsp;)
 782       </table>
 783     </td>
 784   </tr>
 785 </table>
 786 <table cellspacing=5 cellpadding=0 border=0>
 787   <tr>
 788     <td>
 789       &nbsp;
 790     </td>
 791     <td>
 792
 793 <p>
 794
 795 <p>
 796  This macro retrieves a pointer to the object referenced by the sparse matrix list head.<dl compact><dt>
 797 <b>Parameters: </b><dd>
 798 <table border=0 cellspacing=2 cellpadding=0>
 799 <tr><td valign=top><em>head</em>
 800 &nbsp;</td><td>
 801 A pointer to <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.
 802 <p>
 803 </td></tr>
 804 </table>
 805 </dl><dl compact><dt>
 806 <b>Returns: </b><dd>
 807 A pointer to <code>void</code>. </dl>    </td>
 808   </tr>
 809 </table>
 810 <a name="a38" doxytag="dbprim.h.top::sh_size"></a><p>
 811 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 812   <tr>
 813     <td class="md">
 814       <table cellpadding="0" cellspacing="0" border="0">
 815         <tr>
 816           <td nowrap valign="top"><b>
 817 #define sh_size(
 818           </b></td>
 819           <td valign="bottom"><b>
 820 head&nbsp;)
 821       </table>
 822     </td>
 823   </tr>
 824 </table>
 825 <table cellspacing=5 cellpadding=0 border=0>
 826   <tr>
 827     <td>
 828       &nbsp;
 829     </td>
 830     <td>
 831
 832 <p>
 833
 834 <p>
 835  This macro returns the physical size of the memory allocated by the library for this sparse matrix list.
 836 <p>
 837 <dl compact><dt>
 838 <b>Note: </b><dd>
 839 The <a class="el" href="group__dbprim__smat.html#a28">st_size</a>() macro already counts the memory for each list in the table. Summing the results of <a class="el" href="group__dbprim__smat.html#a38">sh_size</a>() and <a class="el" href="group__dbprim__smat.html#a28">st_size</a>() will over-count the amount of memory actually in use.</dl><dl compact><dt>
 840 <b>Parameters: </b><dd>
 841 <table border=0 cellspacing=2 cellpadding=0>
 842 <tr><td valign=top><em>head</em>
 843 &nbsp;</td><td>
 844 A pointer to <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.
 845 <p>
 846 </td></tr>
 847 </table>
 848 </dl><dl compact><dt>
 849 <b>Returns: </b><dd>
 850 A <code>size_t</code>. </dl>    </td>
 851   </tr>
 852 </table>
 853 <a name="a32" doxytag="dbprim.h.top::sh_table"></a><p>
 854 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 855   <tr>
 856     <td class="md">
 857       <table cellpadding="0" cellspacing="0" border="0">
 858         <tr>
 859           <td nowrap valign="top"><b>
 860 #define sh_table(
 861           </b></td>
 862           <td valign="bottom"><b>
 863 head&nbsp;)
 864       </table>
 865     </td>
 866   </tr>
 867 </table>
 868 <table cellspacing=5 cellpadding=0 border=0>
 869   <tr>
 870     <td>
 871       &nbsp;
 872     </td>
 873     <td>
 874
 875 <p>
 876
 877 <p>
 878  If there are any elements in this sparse matrix list head, this macro will retrieve a pointer to the table in which they reside.<dl compact><dt>
 879 <b>Parameters: </b><dd>
 880 <table border=0 cellspacing=2 cellpadding=0>
 881 <tr><td valign=top><em>head</em>
 882 &nbsp;</td><td>
 883 A pointer to <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.
 884 <p>
 885 </td></tr>
 886 </table>
 887 </dl><dl compact><dt>
 888 <b>Returns: </b><dd>
 889 A pointer to <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>. </dl>    </td>
 890   </tr>
 891 </table>
 892 <a name="a30" doxytag="dbprim.h.top::sh_verify"></a><p>
 893 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 894   <tr>
 895     <td class="md">
 896       <table cellpadding="0" cellspacing="0" border="0">
 897         <tr>
 898           <td nowrap valign="top"><b>
 899 #define sh_verify(
 900           </b></td>
 901           <td valign="bottom"><b>
 902 head&nbsp;)
 903       </table>
 904     </td>
 905   </tr>
 906 </table>
 907 <table cellspacing=5 cellpadding=0 border=0>
 908   <tr>
 909     <td>
 910       &nbsp;
 911     </td>
 912     <td>
 913
 914 <p>
 915
 916 <p>
 917  This macro verifies that a given pointer actually does point to a sparse matrix head.<dl compact><dt>
 918 <b>Parameters: </b><dd>
 919 <table border=0 cellspacing=2 cellpadding=0>
 920 <tr><td valign=top><em>head</em>
 921 &nbsp;</td><td>
 922 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>.
 923 <p>
 924 </td></tr>
 925 </table>
 926 </dl><dl compact><dt>
 927 <b>Returns: </b><dd>
 928 Boolean true if <code>head</code> is a valid sparse matrix head or false otherwise. </dl>    </td>
 929   </tr>
 930 </table>
 931 <a name="a26" doxytag="dbprim.h.top::st_count"></a><p>
 932 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 933   <tr>
 934     <td class="md">
 935       <table cellpadding="0" cellspacing="0" border="0">
 936         <tr>
 937           <td nowrap valign="top"><b>
 938 #define st_count(
 939           </b></td>
 940           <td valign="bottom"><b>
 941 table&nbsp;)
 942       </table>
 943     </td>
 944   </tr>
 945 </table>
 946 <table cellspacing=5 cellpadding=0 border=0>
 947   <tr>
 948     <td>
 949       &nbsp;
 950     </td>
 951     <td>
 952
 953 <p>
 954
 955 <p>
 956  This macro retrieves the total number of items actually in the sparse matrix table.<dl compact><dt>
 957 <b>Parameters: </b><dd>
 958 <table border=0 cellspacing=2 cellpadding=0>
 959 <tr><td valign=top><em>table</em>
 960 &nbsp;</td><td>
 961 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>.
 962 <p>
 963 </td></tr>
 964 </table>
 965 </dl><dl compact><dt>
 966 <b>Returns: </b><dd>
 967 An <code>unsigned long</code> containing a count of the number of items in the sparse matrix table. </dl>    </td>
 968   </tr>
 969 </table>
 970 <a name="a27" doxytag="dbprim.h.top::st_extra"></a><p>
 971 <table width="100%" cellpadding="2" cellspacing="0" border="0">
 972   <tr>
 973     <td class="md">
 974       <table cellpadding="0" cellspacing="0" border="0">
 975         <tr>
 976           <td nowrap valign="top"><b>
 977 #define st_extra(
 978           </b></td>
 979           <td valign="bottom"><b>
 980 table&nbsp;)
 981       </table>
 982     </td>
 983   </tr>
 984 </table>
 985 <table cellspacing=5 cellpadding=0 border=0>
 986   <tr>
 987     <td>
 988       &nbsp;
 989     </td>
 990     <td>
 991
 992 <p>
 993
 994 <p>
 995  This macro retrieves the extra pointer data associated with a particular sparse matrix table.<dl compact><dt>
 996 <b>Parameters: </b><dd>
 997 <table border=0 cellspacing=2 cellpadding=0>
 998 <tr><td valign=top><em>table</em>
 999 &nbsp;</td><td>
1000 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>.
1001 <p>
1002 </td></tr>
1003 </table>
1004 </dl><dl compact><dt>
1005 <b>Returns: </b><dd>
1006 A pointer to <code>void</code>. </dl>    </td>
1007   </tr>
1008 </table>
1009 <a name="a23" doxytag="dbprim.h.top::st_flags"></a><p>
1010 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1011   <tr>
1012     <td class="md">
1013       <table cellpadding="0" cellspacing="0" border="0">
1014         <tr>
1015           <td nowrap valign="top"><b>
1016 #define st_flags(
1017           </b></td>
1018           <td valign="bottom"><b>
1019 table&nbsp;)
1020       </table>
1021     </td>
1022   </tr>
1023 </table>
1024 <table cellspacing=5 cellpadding=0 border=0>
1025   <tr>
1026     <td>
1027       &nbsp;
1028     </td>
1029     <td>
1030
1031 <p>
1032
1033 <p>
1034  This macro retrieves the flags associated with the sparse matrix table. Only <a class="el" href="group__dbprim__hash.html#a16">HASH_FLAG_AUTOGROW</a> and <a class="el" href="group__dbprim__hash.html#a17">HASH_FLAG_AUTOSHRINK</a> have any meaning to the application; all other bits are reserved for use in the library. This macro may be used as an lvalue, but care must be taken to avoid modifying the library-specific bits.<dl compact><dt>
1035 <b>Parameters: </b><dd>
1036 <table border=0 cellspacing=2 cellpadding=0>
1037 <tr><td valign=top><em>table</em>
1038 &nbsp;</td><td>
1039 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>.
1040 <p>
1041 </td></tr>
1042 </table>
1043 </dl><dl compact><dt>
1044 <b>Returns: </b><dd>
1045 An <code>unsigned long</code> containing the flags for the sparse matrix table. </dl>    </td>
1046   </tr>
1047 </table>
1048 <a name="a24" doxytag="dbprim.h.top::st_frozen"></a><p>
1049 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1050   <tr>
1051     <td class="md">
1052       <table cellpadding="0" cellspacing="0" border="0">
1053         <tr>
1054           <td nowrap valign="top"><b>
1055 #define st_frozen(
1056           </b></td>
1057           <td valign="bottom"><b>
1058 table&nbsp;)
1059       </table>
1060     </td>
1061   </tr>
1062 </table>
1063 <table cellspacing=5 cellpadding=0 border=0>
1064   <tr>
1065     <td>
1066       &nbsp;
1067     </td>
1068     <td>
1069
1070 <p>
1071
1072 <p>
1073  This macro returns a non-zero value if the matrix is currently frozen. The sparse matrix may be frozen if there is an iteration in progress.<dl compact><dt>
1074 <b>Parameters: </b><dd>
1075 <table border=0 cellspacing=2 cellpadding=0>
1076 <tr><td valign=top><em>table</em>
1077 &nbsp;</td><td>
1078 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>.
1079 <p>
1080 </td></tr>
1081 </table>
1082 </dl><dl compact><dt>
1083 <b>Returns: </b><dd>
1084 A zero value if the matrix is not frozen or a non-zero value if the matrix is frozen. </dl>    </td>
1085   </tr>
1086 </table>
1087 <a name="a25" doxytag="dbprim.h.top::st_modulus"></a><p>
1088 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1089   <tr>
1090     <td class="md">
1091       <table cellpadding="0" cellspacing="0" border="0">
1092         <tr>
1093           <td nowrap valign="top"><b>
1094 #define st_modulus(
1095           </b></td>
1096           <td valign="bottom"><b>
1097 table&nbsp;)
1098       </table>
1099     </td>
1100   </tr>
1101 </table>
1102 <table cellspacing=5 cellpadding=0 border=0>
1103   <tr>
1104     <td>
1105       &nbsp;
1106     </td>
1107     <td>
1108
1109 <p>
1110
1111 <p>
1112  This macro retrieves the number of buckets allocated for the sparse matrix table. An application may wish to save this value between invocations to avoid the overhead of growing the table while filling it with data.<dl compact><dt>
1113 <b>Parameters: </b><dd>
1114 <table border=0 cellspacing=2 cellpadding=0>
1115 <tr><td valign=top><em>table</em>
1116 &nbsp;</td><td>
1117 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>.
1118 <p>
1119 </td></tr>
1120 </table>
1121 </dl><dl compact><dt>
1122 <b>Returns: </b><dd>
1123 An <code>unsigned long</code> containing the number of buckets allocated for the sparse matrix table. </dl>    </td>
1124   </tr>
1125 </table>
1126 <a name="a28" doxytag="dbprim.h.top::st_size"></a><p>
1127 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1128   <tr>
1129     <td class="md">
1130       <table cellpadding="0" cellspacing="0" border="0">
1131         <tr>
1132           <td nowrap valign="top"><b>
1133 #define st_size(
1134           </b></td>
1135           <td valign="bottom"><b>
1136 table&nbsp;)
1137       </table>
1138     </td>
1139   </tr>
1140 </table>
1141 <table cellspacing=5 cellpadding=0 border=0>
1142   <tr>
1143     <td>
1144       &nbsp;
1145     </td>
1146     <td>
1147
1148 <p>
1149
1150 <p>
1151  This macro returns the physical size of the memory allocated by the library for this sparse matrix table.
1152 <p>
1153 <dl compact><dt>
1154 <b>Note: </b><dd>
1155 The <a class="el" href="group__dbprim__smat.html#a28">st_size</a>() macro already counts the memory for each list in the table. Summing the results of <a class="el" href="group__dbprim__smat.html#a38">sh_size</a>() and <a class="el" href="group__dbprim__smat.html#a28">st_size</a>() will over-count the amount of memory actually in use.</dl><dl compact><dt>
1156 <b>Parameters: </b><dd>
1157 <table border=0 cellspacing=2 cellpadding=0>
1158 <tr><td valign=top><em>table</em>
1159 &nbsp;</td><td>
1160 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>.
1161 <p>
1162 </td></tr>
1163 </table>
1164 </dl><dl compact><dt>
1165 <b>Returns: </b><dd>
1166 A <code>size_t</code>. </dl>    </td>
1167   </tr>
1168 </table>
1169 <a name="a22" doxytag="dbprim.h.top::st_verify"></a><p>
1170 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1171   <tr>
1172     <td class="md">
1173       <table cellpadding="0" cellspacing="0" border="0">
1174         <tr>
1175           <td nowrap valign="top"><b>
1176 #define st_verify(
1177           </b></td>
1178           <td valign="bottom"><b>
1179 table&nbsp;)
1180       </table>
1181     </td>
1182   </tr>
1183 </table>
1184 <table cellspacing=5 cellpadding=0 border=0>
1185   <tr>
1186     <td>
1187       &nbsp;
1188     </td>
1189     <td>
1190
1191 <p>
1192
1193 <p>
1194  This macro verifies that a given pointer actually does point to a sparse matrix table.<dl compact><dt>
1195 <b>Parameters: </b><dd>
1196 <table border=0 cellspacing=2 cellpadding=0>
1197 <tr><td valign=top><em>table</em>
1198 &nbsp;</td><td>
1199 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>.
1200 <p>
1201 </td></tr>
1202 </table>
1203 </dl><dl compact><dt>
1204 <b>Returns: </b><dd>
1205 Boolean true if <code>table</code> is a valid sparse matrix table or false otherwise. </dl>    </td>
1206   </tr>
1207 </table>
1208 <hr><h2>Typedef Documentation</h2>
1209 <a name="a5" doxytag="dbprim.h.top::smat_comp_t"></a><p>
1210 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1211   <tr>
1212     <td class="md">
1213       <table cellpadding="0" cellspacing="0" border="0">
1214         <tr>
1215           <td nowrap valign="top"><b>
1216 typedef unsigned long(* smat_comp_t)(<a class="el" href="group__dbprim__key.html#a0">db_key_t</a> *, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *)
1217           </b></td>
1218         </tr>
1219
1220       </table>
1221     </td>
1222   </tr>
1223 </table>
1224 <table cellspacing=5 cellpadding=0 border=0>
1225   <tr>
1226     <td>
1227       &nbsp;
1228     </td>
1229     <td>
1230
1231 <p>
1232
1233 <p>
1234  This function pointer references a callback used by <a class="el" href="group__dbprim__smat.html#a19">sh_find</a>(). It should return 0 if the sparse matrix entry represented by the second argument matches the key passed as the first argument.     </td>
1235   </tr>
1236 </table>
1237 <a name="a2" doxytag="dbprim.h.top::smat_entry_t"></a><p>
1238 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1239   <tr>
1240     <td class="md">
1241       <table cellpadding="0" cellspacing="0" border="0">
1242         <tr>
1243           <td nowrap valign="top"><b>
1244 typedef struct _smat_entry_s smat_entry_t
1245           </b></td>
1246         </tr>
1247
1248       </table>
1249     </td>
1250   </tr>
1251 </table>
1252 <table cellspacing=5 cellpadding=0 border=0>
1253   <tr>
1254     <td>
1255       &nbsp;
1256     </td>
1257     <td>
1258
1259 <p>
1260
1261 <p>
1262  This structure is allocated by the library and represents a single element in a sparse matrix.     </td>
1263   </tr>
1264 </table>
1265 <a name="a1" doxytag="dbprim.h.top::smat_head_t"></a><p>
1266 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1267   <tr>
1268     <td class="md">
1269       <table cellpadding="0" cellspacing="0" border="0">
1270         <tr>
1271           <td nowrap valign="top"><b>
1272 typedef struct _smat_head_s smat_head_t
1273           </b></td>
1274         </tr>
1275
1276       </table>
1277     </td>
1278   </tr>
1279 </table>
1280 <table cellspacing=5 cellpadding=0 border=0>
1281   <tr>
1282     <td>
1283       &nbsp;
1284     </td>
1285     <td>
1286
1287 <p>
1288
1289 <p>
1290  This structure is the head of a linked list of sparse matrix entries.     </td>
1291   </tr>
1292 </table>
1293 <a name="a4" doxytag="dbprim.h.top::smat_iter_t"></a><p>
1294 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1295   <tr>
1296     <td class="md">
1297       <table cellpadding="0" cellspacing="0" border="0">
1298         <tr>
1299           <td nowrap valign="top"><b>
1300 typedef unsigned long(* smat_iter_t)(<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *, <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> *, void *)
1301           </b></td>
1302         </tr>
1303
1304       </table>
1305     </td>
1306   </tr>
1307 </table>
1308 <table cellspacing=5 cellpadding=0 border=0>
1309   <tr>
1310     <td>
1311       &nbsp;
1312     </td>
1313     <td>
1314
1315 <p>
1316
1317 <p>
1318  This function pointer references a callback used by <a class="el" href="group__dbprim__smat.html#a13">st_iter</a>(), <a class="el" href="group__dbprim__smat.html#a14">st_flush</a>(), <a class="el" href="group__dbprim__smat.html#a20">sh_iter</a>(), and sh_flush(). It should return 0 for success. A non-zero return value will terminate the operation and will become the return value of the call.     </td>
1319   </tr>
1320 </table>
1321 <a name="a6" doxytag="dbprim.h.top::smat_loc_t"></a><p>
1322 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1323   <tr>
1324     <td class="md">
1325       <table cellpadding="0" cellspacing="0" border="0">
1326         <tr>
1327           <td nowrap valign="top"><b>
1328 typedef enum <a class="el" href="group__dbprim__smat.html#a48">_smat_loc_e</a> smat_loc_t
1329           </b></td>
1330         </tr>
1331
1332       </table>
1333     </td>
1334   </tr>
1335 </table>
1336 <table cellspacing=5 cellpadding=0 border=0>
1337   <tr>
1338     <td>
1339       &nbsp;
1340     </td>
1341     <td>
1342
1343 <p>
1344
1345 <p>
1346  See the documentation for the enumeration <a class="el" href="group__dbprim__smat.html#a48">_smat_loc_e</a>.     </td>
1347   </tr>
1348 </table>
1349 <a name="a3" doxytag="dbprim.h.top::smat_resize_t"></a><p>
1350 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1351   <tr>
1352     <td class="md">
1353       <table cellpadding="0" cellspacing="0" border="0">
1354         <tr>
1355           <td nowrap valign="top"><b>
1356 typedef unsigned long(* smat_resize_t)(<a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> *, unsigned long)
1357           </b></td>
1358         </tr>
1359
1360       </table>
1361     </td>
1362   </tr>
1363 </table>
1364 <table cellspacing=5 cellpadding=0 border=0>
1365   <tr>
1366     <td>
1367       &nbsp;
1368     </td>
1369     <td>
1370
1371 <p>
1372
1373 <p>
1374  This function pointer references a callback that will be called with both the old and new sparse matrix table sizes whenever a sparse matrix's hash table table is resized. It should return non-zero only when the resize should be inhibited.     </td>
1375   </tr>
1376 </table>
1377 <a name="a0" doxytag="dbprim.h.top::smat_table_t"></a><p>
1378 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1379   <tr>
1380     <td class="md">
1381       <table cellpadding="0" cellspacing="0" border="0">
1382         <tr>
1383           <td nowrap valign="top"><b>
1384 typedef struct _smat_table_s smat_table_t
1385           </b></td>
1386         </tr>
1387
1388       </table>
1389     </td>
1390   </tr>
1391 </table>
1392 <table cellspacing=5 cellpadding=0 border=0>
1393   <tr>
1394     <td>
1395       &nbsp;
1396     </td>
1397     <td>
1398
1399 <p>
1400
1401 <p>
1402  This structure is the basis of all sparse matrices maintained by this library.     </td>
1403   </tr>
1404 </table>
1405 <hr><h2>Enumeration Type Documentation</h2>
1406 <a name="a48" doxytag="dbprim.h.top::_smat_loc_e"></a><p>
1407 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1408   <tr>
1409     <td class="md">
1410       <table cellpadding="0" cellspacing="0" border="0">
1411         <tr>
1412           <td nowrap valign="top"><b>
1413 enum _smat_loc_e
1414           </b></td>
1415         </tr>
1416
1417       </table>
1418     </td>
1419   </tr>
1420 </table>
1421 <table cellspacing=5 cellpadding=0 border=0>
1422   <tr>
1423     <td>
1424       &nbsp;
1425     </td>
1426     <td>
1427
1428 <p>
1429
1430 <p>
1431  This enumeration is used to specify whether an element is a row or column element. It should be referenced by the typedef <a class="el" href="group__dbprim__smat.html#a6">smat_loc_t</a>. <dl compact><dt>
1432 <b>Enumeration values:</b><dd>
1433 <table border=0 cellspacing=2 cellpadding=0>
1434 <tr><td valign=top><a name="a48a102" doxytag="SMAT_LOC_FIRST"></a><em>SMAT_LOC_FIRST</em>
1435 &nbsp;</td><td>
1436 First entry (``row''). </td></tr>
1437 <tr><td valign=top><a name="a48a103" doxytag="SMAT_LOC_SECOND"></a><em>SMAT_LOC_SECOND</em>
1438 &nbsp;</td><td>
1439 Second entry (``column''). </td></tr>
1440 </table>
1441 </dl>
1442     </td>
1443   </tr>
1444 </table>
1445 <hr><h2>Function Documentation</h2>
1446 <a name="a19" doxytag="sh_find.c::sh_find"></a><p>
1447 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1448   <tr>
1449     <td class="md">
1450       <table cellpadding="0" cellspacing="0" border="0">
1451         <tr>
1452           <td nowrap valign="top"><b>
1453 unsigned long sh_find (
1454           </b></td>
1455           <td valign="bottom"><b>
1456 <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> * <em>head</em>,
1457           </b></td>
1458         </tr>
1459         <tr>
1460           <td></td>
1461           <td><b>
1462 <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> ** <em>elem_p</em>,
1463           </b></td>
1464         </tr>
1465         <tr>
1466           <td></td>
1467           <td><b>
1468 <a class="el" href="group__dbprim__smat.html#a5">smat_comp_t</a> <em>comp_func</em>,
1469           </b></td>
1470         </tr>
1471         <tr>
1472           <td></td>
1473           <td><b>
1474 <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> * <em>start</em>,
1475           </b></td>
1476         </tr>
1477         <tr>
1478           <td></td>
1479           <td><b>
1480 <a class="el" href="group__dbprim__key.html#a0">db_key_t</a> * <em>key</em>&nbsp;)
1481           </b></td>
1482         </tr>
1483
1484       </table>
1485     </td>
1486   </tr>
1487 </table>
1488 <table cellspacing=5 cellpadding=0 border=0>
1489   <tr>
1490     <td>
1491       &nbsp;
1492     </td>
1493     <td>
1494
1495 <p>
1496
1497 <p>
1498  This function iterates through the given row or column of a sparse matrix looking for an element that matches the given <code>key</code>.<dl compact><dt>
1499 <b>Parameters: </b><dd>
1500 <table border=0 cellspacing=2 cellpadding=0>
1501 <tr><td valign=top><em>head</em>
1502 &nbsp;</td><td>
1503 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>. </td></tr>
1504 <tr><td valign=top><em>elem_p</em>
1505 &nbsp;</td><td>
1506 A pointer to a pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. This is a result pramater. <code>NULL</code> is an invalid value. </td></tr>
1507 <tr><td valign=top><em>comp_func</em>
1508 &nbsp;</td><td>
1509 A pointer to a comparison function used to compare the key to a particular entry. See the documentation for <a class="el" href="group__dbprim__smat.html#a5">smat_comp_t</a> for more information. </td></tr>
1510 <tr><td valign=top><em>start</em>
1511 &nbsp;</td><td>
1512 A pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> describing where in the row or column to start. If <code>NULL</code> is passed, the beginning of the row or column will be assumed. </td></tr>
1513 <tr><td valign=top><em>key</em>
1514 &nbsp;</td><td>
1515 A key to search for.</td></tr>
1516 </table>
1517 </dl><dl compact><dt>
1518 <b>Return values: </b><dd>
1519 <table border=0 cellspacing=2 cellpadding=0>
1520 <tr><td valign=top><em>DB_ERR_BADARGS</em>
1521 &nbsp;</td><td>
1522 An argument was invalid. </td></tr>
1523 <tr><td valign=top><em>DB_ERR_WRONGTABLE</em>
1524 &nbsp;</td><td>
1525 <code>start</code> is not in this row or column. </td></tr>
1526 <tr><td valign=top><em>DB_ERR_NOENTRY</em>
1527 &nbsp;</td><td>
1528 No matching entry was found. </td></tr>
1529 </table>
1530 </dl>    </td>
1531   </tr>
1532 </table>
1533 <a name="a17" doxytag="sh_init.c::sh_init"></a><p>
1534 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1535   <tr>
1536     <td class="md">
1537       <table cellpadding="0" cellspacing="0" border="0">
1538         <tr>
1539           <td nowrap valign="top"><b>
1540 unsigned long sh_init (
1541           </b></td>
1542           <td valign="bottom"><b>
1543 <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> * <em>head</em>,
1544           </b></td>
1545         </tr>
1546         <tr>
1547           <td></td>
1548           <td><b>
1549 <a class="el" href="group__dbprim__smat.html#a6">smat_loc_t</a> <em>elem</em>,
1550           </b></td>
1551         </tr>
1552         <tr>
1553           <td></td>
1554           <td><b>
1555 void * <em>object</em>&nbsp;)
1556           </b></td>
1557         </tr>
1558
1559       </table>
1560     </td>
1561   </tr>
1562 </table>
1563 <table cellspacing=5 cellpadding=0 border=0>
1564   <tr>
1565     <td>
1566       &nbsp;
1567     </td>
1568     <td>
1569
1570 <p>
1571
1572 <p>
1573  This function dynamically initializes a sparse matrix row or column linked list head. The <code>elem</code> argument specifies whether the object is to be associated with a <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a> list or a <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a> list.<dl compact><dt>
1574 <b>Parameters: </b><dd>
1575 <table border=0 cellspacing=2 cellpadding=0>
1576 <tr><td valign=top><em>head</em>
1577 &nbsp;</td><td>
1578 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> to be initialized. </td></tr>
1579 <tr><td valign=top><em>elem</em>
1580 &nbsp;</td><td>
1581 Either <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a> or <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a>. </td></tr>
1582 <tr><td valign=top><em>object</em>
1583 &nbsp;</td><td>
1584 A pointer to the object containing the sparse matrix row or column head.</td></tr>
1585 </table>
1586 </dl><dl compact><dt>
1587 <b>Return values: </b><dd>
1588 <table border=0 cellspacing=2 cellpadding=0>
1589 <tr><td valign=top><em>DB_ERR_BADARGS</em>
1590 &nbsp;</td><td>
1591 An invalid argument was given. </td></tr>
1592 </table>
1593 </dl>    </td>
1594   </tr>
1595 </table>
1596 <a name="a20" doxytag="sh_iter.c::sh_iter"></a><p>
1597 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1598   <tr>
1599     <td class="md">
1600       <table cellpadding="0" cellspacing="0" border="0">
1601         <tr>
1602           <td nowrap valign="top"><b>
1603 unsigned long sh_iter (
1604           </b></td>
1605           <td valign="bottom"><b>
1606 <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> * <em>head</em>,
1607           </b></td>
1608         </tr>
1609         <tr>
1610           <td></td>
1611           <td><b>
1612 <a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> <em>iter_func</em>,
1613           </b></td>
1614         </tr>
1615         <tr>
1616           <td></td>
1617           <td><b>
1618 void * <em>extra</em>&nbsp;)
1619           </b></td>
1620         </tr>
1621
1622       </table>
1623     </td>
1624   </tr>
1625 </table>
1626 <table cellspacing=5 cellpadding=0 border=0>
1627   <tr>
1628     <td>
1629       &nbsp;
1630     </td>
1631     <td>
1632
1633 <p>
1634
1635 <p>
1636  This function iterates over a row or column of a sparse matrix, executing the given <code>iter_func</code> for each entry.<dl compact><dt>
1637 <b>Parameters: </b><dd>
1638 <table border=0 cellspacing=2 cellpadding=0>
1639 <tr><td valign=top><em>head</em>
1640 &nbsp;</td><td>
1641 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>. </td></tr>
1642 <tr><td valign=top><em>iter_func</em>
1643 &nbsp;</td><td>
1644 A pointer to a callback function used to perform user-specified actions on an entry in a row or column of a sparse matrix. <code>NULL</code> is an invalid value. See the documentation for <a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> for more information. </td></tr>
1645 <tr><td valign=top><em>extra</em>
1646 &nbsp;</td><td>
1647 A <code>void</code> pointer that will be passed to <code>iter_func</code>.</td></tr>
1648 </table>
1649 </dl><dl compact><dt>
1650 <b>Return values: </b><dd>
1651 <table border=0 cellspacing=2 cellpadding=0>
1652 <tr><td valign=top><em>DB_ERR_BADARGS</em>
1653 &nbsp;</td><td>
1654 An argument was invalid. </td></tr>
1655 </table>
1656 </dl>    </td>
1657   </tr>
1658 </table>
1659 <a name="a18" doxytag="sh_move.c::sh_move"></a><p>
1660 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1661   <tr>
1662     <td class="md">
1663       <table cellpadding="0" cellspacing="0" border="0">
1664         <tr>
1665           <td nowrap valign="top"><b>
1666 unsigned long sh_move (
1667           </b></td>
1668           <td valign="bottom"><b>
1669 <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> * <em>head</em>,
1670           </b></td>
1671         </tr>
1672         <tr>
1673           <td></td>
1674           <td><b>
1675 <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> * <em>elem</em>,
1676           </b></td>
1677         </tr>
1678         <tr>
1679           <td></td>
1680           <td><b>
1681 <a class="el" href="group__dbprim__link.html#a4">link_loc_t</a> <em>loc</em>,
1682           </b></td>
1683         </tr>
1684         <tr>
1685           <td></td>
1686           <td><b>
1687 <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> * <em>elem2</em>&nbsp;)
1688           </b></td>
1689         </tr>
1690
1691       </table>
1692     </td>
1693   </tr>
1694 </table>
1695 <table cellspacing=5 cellpadding=0 border=0>
1696   <tr>
1697     <td>
1698       &nbsp;
1699     </td>
1700     <td>
1701
1702 <p>
1703
1704 <p>
1705  This function allows the specified entry to be shifted within the linked list describing the row or column. It is very similar to the <a class="el" href="group__dbprim__link.html#a7">ll_move</a>() function.<dl compact><dt>
1706 <b>Parameters: </b><dd>
1707 <table border=0 cellspacing=2 cellpadding=0>
1708 <tr><td valign=top><em>head</em>
1709 &nbsp;</td><td>
1710 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a>. </td></tr>
1711 <tr><td valign=top><em>elem</em>
1712 &nbsp;</td><td>
1713 A pointer to the <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> describing the entry to be moved. </td></tr>
1714 <tr><td valign=top><em>loc</em>
1715 &nbsp;</td><td>
1716 A <a class="el" href="group__dbprim__link.html#a4">link_loc_t</a> indicating where the entry should be moved to. </td></tr>
1717 <tr><td valign=top><em>elem2</em>
1718 &nbsp;</td><td>
1719 A pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> describing another entry in the list if <code>loc</code> is <a class="el" href="group__dbprim__link.html#a26a100">LINK_LOC_BEFORE</a> or <a class="el" href="group__dbprim__link.html#a26a101">LINK_LOC_AFTER</a>.</td></tr>
1720 </table>
1721 </dl><dl compact><dt>
1722 <b>Return values: </b><dd>
1723 <table border=0 cellspacing=2 cellpadding=0>
1724 <tr><td valign=top><em>DB_ERR_BADARGS</em>
1725 &nbsp;</td><td>
1726 An argument was invalid. </td></tr>
1727 <tr><td valign=top><em>DB_ERR_BUSY</em>
1728 &nbsp;</td><td>
1729 <code>elem</code> and <code>elem2</code> are the same entry. </td></tr>
1730 <tr><td valign=top><em>DB_ERR_WRONGTABLE</em>
1731 &nbsp;</td><td>
1732 <code>elem</code> or <code>elem2</code> are in a different row or column. </td></tr>
1733 <tr><td valign=top><em>DB_ERR_UNUSED</em>
1734 &nbsp;</td><td>
1735 <code>elem</code> or <code>elem2</code> are not in any row or column. </td></tr>
1736 </table>
1737 </dl>    </td>
1738   </tr>
1739 </table>
1740 <a name="a7" doxytag="smat_freelist.c::smat_cleanup"></a><p>
1741 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1742   <tr>
1743     <td class="md">
1744       <table cellpadding="0" cellspacing="0" border="0">
1745         <tr>
1746           <td nowrap valign="top"><b>
1747 unsigned long smat_cleanup (
1748           </b></td>
1749           <td valign="bottom"><b>
1750 void&nbsp;)
1751           </b></td>
1752         </tr>
1753
1754       </table>
1755     </td>
1756   </tr>
1757 </table>
1758 <table cellspacing=5 cellpadding=0 border=0>
1759   <tr>
1760     <td>
1761       &nbsp;
1762     </td>
1763     <td>
1764
1765 <p>
1766
1767 <p>
1768  This function frees all smat_entry_t objects on the internal free list. It is always successful and returns 0.     </td>
1769   </tr>
1770 </table>
1771 <a name="a8" doxytag="smat_freelist.c::smat_freemem"></a><p>
1772 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1773   <tr>
1774     <td class="md">
1775       <table cellpadding="0" cellspacing="0" border="0">
1776         <tr>
1777           <td nowrap valign="top"><b>
1778 unsigned long smat_freemem (
1779           </b></td>
1780           <td valign="bottom"><b>
1781 void&nbsp;)
1782           </b></td>
1783         </tr>
1784
1785       </table>
1786     </td>
1787   </tr>
1788 </table>
1789 <table cellspacing=5 cellpadding=0 border=0>
1790   <tr>
1791     <td>
1792       &nbsp;
1793     </td>
1794     <td>
1795
1796 <p>
1797
1798 <p>
1799  This function returns the amount of memory being used by the internal free list of smat_entry_t objects.
1800 <p>
1801 <dl compact><dt>
1802 <b>Returns: </b><dd>
1803 A number indicating the size, in bytes, of the memory allocated for smat_entry_t objects on the free list. </dl>    </td>
1804   </tr>
1805 </table>
1806 <a name="a10" doxytag="st_add.c::st_add"></a><p>
1807 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1808   <tr>
1809     <td class="md">
1810       <table cellpadding="0" cellspacing="0" border="0">
1811         <tr>
1812           <td nowrap valign="top"><b>
1813 unsigned long st_add (
1814           </b></td>
1815           <td valign="bottom"><b>
1816 <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> * <em>table</em>,
1817           </b></td>
1818         </tr>
1819         <tr>
1820           <td></td>
1821           <td><b>
1822 <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> ** <em>entry_p</em>,
1823           </b></td>
1824         </tr>
1825         <tr>
1826           <td></td>
1827           <td><b>
1828 <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> * <em>head1</em>,
1829           </b></td>
1830         </tr>
1831         <tr>
1832           <td></td>
1833           <td><b>
1834 <a class="el" href="group__dbprim__link.html#a4">link_loc_t</a> <em>loc1</em>,
1835           </b></td>
1836         </tr>
1837         <tr>
1838           <td></td>
1839           <td><b>
1840 <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> * <em>ent1</em>,
1841           </b></td>
1842         </tr>
1843         <tr>
1844           <td></td>
1845           <td><b>
1846 <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> * <em>head2</em>,
1847           </b></td>
1848         </tr>
1849         <tr>
1850           <td></td>
1851           <td><b>
1852 <a class="el" href="group__dbprim__link.html#a4">link_loc_t</a> <em>loc2</em>,
1853           </b></td>
1854         </tr>
1855         <tr>
1856           <td></td>
1857           <td><b>
1858 <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> * <em>ent2</em>&nbsp;)
1859           </b></td>
1860         </tr>
1861
1862       </table>
1863     </td>
1864   </tr>
1865 </table>
1866 <table cellspacing=5 cellpadding=0 border=0>
1867   <tr>
1868     <td>
1869       &nbsp;
1870     </td>
1871     <td>
1872
1873 <p>
1874
1875 <p>
1876  This function adds an entry to a sparse matrix. The entry is referenced in three different places, thus the complex set of arguments. This function will allocate a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> and return it through the <code>entry_p</code> result parameter.<dl compact><dt>
1877 <b>Parameters: </b><dd>
1878 <table border=0 cellspacing=2 cellpadding=0>
1879 <tr><td valign=top><em>table</em>
1880 &nbsp;</td><td>
1881 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>. </td></tr>
1882 <tr><td valign=top><em>entry_p</em>
1883 &nbsp;</td><td>
1884 A pointer to a pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. This is a result parameter. If <code>NULL</code> is passed, the addition will be performed and an appropriate error code returned. </td></tr>
1885 <tr><td valign=top><em>head1</em>
1886 &nbsp;</td><td>
1887 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> representing a <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a> sparse matrix list. </td></tr>
1888 <tr><td valign=top><em>loc1</em>
1889 &nbsp;</td><td>
1890 A <a class="el" href="group__dbprim__link.html#a4">link_loc_t</a> indicating where the entry should be added for <code>head1</code>. </td></tr>
1891 <tr><td valign=top><em>ent1</em>
1892 &nbsp;</td><td>
1893 A pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> describing another element in the list represented by <code>head1</code> if <code>loc1</code> is <a class="el" href="group__dbprim__link.html#a26a100">LINK_LOC_BEFORE</a> or <a class="el" href="group__dbprim__link.html#a26a101">LINK_LOC_AFTER</a>. </td></tr>
1894 <tr><td valign=top><em>head2</em>
1895 &nbsp;</td><td>
1896 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> representing a <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a> sparse matrix list. </td></tr>
1897 <tr><td valign=top><em>loc2</em>
1898 &nbsp;</td><td>
1899 A <a class="el" href="group__dbprim__link.html#a4">link_loc_t</a> indicating where the entry should be added for <code>head2</code>. </td></tr>
1900 <tr><td valign=top><em>ent2</em>
1901 &nbsp;</td><td>
1902 A pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> describing another element in the list represented by <code>head2</code> if <code>loc2</code> is <a class="el" href="group__dbprim__link.html#a26a100">LINK_LOC_BEFORE</a> or <a class="el" href="group__dbprim__link.html#a26a101">LINK_LOC_AFTER</a>.</td></tr>
1903 </table>
1904 </dl><dl compact><dt>
1905 <b>Return values: </b><dd>
1906 <table border=0 cellspacing=2 cellpadding=0>
1907 <tr><td valign=top><em>DB_ERR_BADARGS</em>
1908 &nbsp;</td><td>
1909 An argument was invalid. </td></tr>
1910 <tr><td valign=top><em>DB_ERR_BUSY</em>
1911 &nbsp;</td><td>
1912 One of the arguments is already in the table. </td></tr>
1913 <tr><td valign=top><em>DB_ERR_FROZEN</em>
1914 &nbsp;</td><td>
1915 The table is currently frozen. </td></tr>
1916 <tr><td valign=top><em>DB_ERR_NOTABLE</em>
1917 &nbsp;</td><td>
1918 The bucket table has not been allocated and automatic growth is not enabled. </td></tr>
1919 <tr><td valign=top><em>DB_ERR_WRONGTABLE</em>
1920 &nbsp;</td><td>
1921 One of the arguments was not in the proper table or list. </td></tr>
1922 <tr><td valign=top><em>DB_ERR_UNUSED</em>
1923 &nbsp;</td><td>
1924 One of the <code>ent</code> arguments is not presently in a list. </td></tr>
1925 <tr><td valign=top><em>DB_ERR_UNRECOVERABLE</em>
1926 &nbsp;</td><td>
1927 An unrecoverable error occurred while resizing the table. </td></tr>
1928 <tr><td valign=top><em>ENOMEM</em>
1929 &nbsp;</td><td>
1930 No memory could be allocated for the <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> structure. </td></tr>
1931 </table>
1932 </dl>    </td>
1933   </tr>
1934 </table>
1935 <a name="a12" doxytag="st_find.c::st_find"></a><p>
1936 <table width="100%" cellpadding="2" cellspacing="0" border="0">
1937   <tr>
1938     <td class="md">
1939       <table cellpadding="0" cellspacing="0" border="0">
1940         <tr>
1941           <td nowrap valign="top"><b>
1942 unsigned long st_find (
1943           </b></td>
1944           <td valign="bottom"><b>
1945 <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> * <em>table</em>,
1946           </b></td>
1947         </tr>
1948         <tr>
1949           <td></td>
1950           <td><b>
1951 <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> ** <em>entry_p</em>,
1952           </b></td>
1953         </tr>
1954         <tr>
1955           <td></td>
1956           <td><b>
1957 <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> * <em>head1</em>,
1958           </b></td>
1959         </tr>
1960         <tr>
1961           <td></td>
1962           <td><b>
1963 <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> * <em>head2</em>&nbsp;)
1964           </b></td>
1965         </tr>
1966
1967       </table>
1968     </td>
1969   </tr>
1970 </table>
1971 <table cellspacing=5 cellpadding=0 border=0>
1972   <tr>
1973     <td>
1974       &nbsp;
1975     </td>
1976     <td>
1977
1978 <p>
1979
1980 <p>
1981  This function looks up the entry matching the given <code>head1</code> and <code>head2</code>.<dl compact><dt>
1982 <b>Parameters: </b><dd>
1983 <table border=0 cellspacing=2 cellpadding=0>
1984 <tr><td valign=top><em>table</em>
1985 &nbsp;</td><td>
1986 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>. </td></tr>
1987 <tr><td valign=top><em>entry_p</em>
1988 &nbsp;</td><td>
1989 A pointer to a pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a>. This is a result parameter. If <code>NULL</code> is passed, the lookup will be performed and an appropriate error code returned. </td></tr>
1990 <tr><td valign=top><em>head1</em>
1991 &nbsp;</td><td>
1992 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> initialized to <a class="el" href="group__dbprim__smat.html#a48a102">SMAT_LOC_FIRST</a>. </td></tr>
1993 <tr><td valign=top><em>head2</em>
1994 &nbsp;</td><td>
1995 A pointer to a <a class="el" href="group__dbprim__smat.html#a1">smat_head_t</a> initialized to <a class="el" href="group__dbprim__smat.html#a48a103">SMAT_LOC_SECOND</a>.</td></tr>
1996 </table>
1997 </dl><dl compact><dt>
1998 <b>Return values: </b><dd>
1999 <table border=0 cellspacing=2 cellpadding=0>
2000 <tr><td valign=top><em>DB_ERR_BADARGS</em>
2001 &nbsp;</td><td>
2002 An argument was invalid. </td></tr>
2003 <tr><td valign=top><em>DB_ERR_WRONGTABLE</em>
2004 &nbsp;</td><td>
2005 One or both of <code>head1</code> or <code>head2</code> are not referenced in this table. </td></tr>
2006 <tr><td valign=top><em>DB_ERR_NOENTRY</em>
2007 &nbsp;</td><td>
2008 No matching entry was found. </td></tr>
2009 </table>
2010 </dl>    </td>
2011   </tr>
2012 </table>
2013 <a name="a14" doxytag="st_flush.c::st_flush"></a><p>
2014 <table width="100%" cellpadding="2" cellspacing="0" border="0">
2015   <tr>
2016     <td class="md">
2017       <table cellpadding="0" cellspacing="0" border="0">
2018         <tr>
2019           <td nowrap valign="top"><b>
2020 unsigned long st_flush (
2021           </b></td>
2022           <td valign="bottom"><b>
2023 <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> * <em>table</em>,
2024           </b></td>
2025         </tr>
2026         <tr>
2027           <td></td>
2028           <td><b>
2029 <a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> <em>flush_func</em>,
2030           </b></td>
2031         </tr>
2032         <tr>
2033           <td></td>
2034           <td><b>
2035 void * <em>extra</em>&nbsp;)
2036           </b></td>
2037         </tr>
2038
2039       </table>
2040     </td>
2041   </tr>
2042 </table>
2043 <table cellspacing=5 cellpadding=0 border=0>
2044   <tr>
2045     <td>
2046       &nbsp;
2047     </td>
2048     <td>
2049
2050 <p>
2051
2052 <p>
2053  This function flushes a sparse matrix--that is, it removes each entry from the matrix. If a <code>flush_func</code> is specified, it will be called on the entry after it has been removed from the table, and may safely call <code>free()</code>.<dl compact><dt>
2054 <b>Parameters: </b><dd>
2055 <table border=0 cellspacing=2 cellpadding=0>
2056 <tr><td valign=top><em>table</em>
2057 &nbsp;</td><td>
2058 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>. </td></tr>
2059 <tr><td valign=top><em>flush_func</em>
2060 &nbsp;</td><td>
2061 A pointer to a callback function used to perform user-specified actions on an entry after removing it from the table. May be <code>NULL</code>. See the documentation for <a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> for more information. </td></tr>
2062 <tr><td valign=top><em>extra</em>
2063 &nbsp;</td><td>
2064 A <code>void</code> pointer that will be passed to <code>iter_func</code>.</td></tr>
2065 </table>
2066 </dl><dl compact><dt>
2067 <b>Return values: </b><dd>
2068 <table border=0 cellspacing=2 cellpadding=0>
2069 <tr><td valign=top><em>DB_ERR_BADARGS</em>
2070 &nbsp;</td><td>
2071 An argument was invalid. </td></tr>
2072 <tr><td valign=top><em>DB_ERR_FROZEN</em>
2073 &nbsp;</td><td>
2074 The sparse matrix is frozen. </td></tr>
2075 </table>
2076 </dl>    </td>
2077   </tr>
2078 </table>
2079 <a name="a16" doxytag="st_free.c::st_free"></a><p>
2080 <table width="100%" cellpadding="2" cellspacing="0" border="0">
2081   <tr>
2082     <td class="md">
2083       <table cellpadding="0" cellspacing="0" border="0">
2084         <tr>
2085           <td nowrap valign="top"><b>
2086 unsigned long st_free (
2087           </b></td>
2088           <td valign="bottom"><b>
2089 <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> * <em>table</em>&nbsp;)
2090           </b></td>
2091         </tr>
2092
2093       </table>
2094     </td>
2095   </tr>
2096 </table>
2097 <table cellspacing=5 cellpadding=0 border=0>
2098   <tr>
2099     <td>
2100       &nbsp;
2101     </td>
2102     <td>
2103
2104 <p>
2105
2106 <p>
2107  This function releases the memory used by the bucket table of the empty hash table associated with a sparse matrix.<dl compact><dt>
2108 <b>Parameters: </b><dd>
2109 <table border=0 cellspacing=2 cellpadding=0>
2110 <tr><td valign=top><em>table</em>
2111 &nbsp;</td><td>
2112 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>.</td></tr>
2113 </table>
2114 </dl><dl compact><dt>
2115 <b>Return values: </b><dd>
2116 <table border=0 cellspacing=2 cellpadding=0>
2117 <tr><td valign=top><em>DB_ERR_BADARGS</em>
2118 &nbsp;</td><td>
2119 An invalid argument was given. </td></tr>
2120 <tr><td valign=top><em>DB_ERR_FROZEN</em>
2121 &nbsp;</td><td>
2122 The table is frozen. </td></tr>
2123 <tr><td valign=top><em>DB_ERR_NOTEMPTY</em>
2124 &nbsp;</td><td>
2125 The table is not empty. </td></tr>
2126 </table>
2127 </dl>    </td>
2128   </tr>
2129 </table>
2130 <a name="a9" doxytag="st_init.c::st_init"></a><p>
2131 <table width="100%" cellpadding="2" cellspacing="0" border="0">
2132   <tr>
2133     <td class="md">
2134       <table cellpadding="0" cellspacing="0" border="0">
2135         <tr>
2136           <td nowrap valign="top"><b>
2137 unsigned long st_init (
2138           </b></td>
2139           <td valign="bottom"><b>
2140 <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> * <em>table</em>,
2141           </b></td>
2142         </tr>
2143         <tr>
2144           <td></td>
2145           <td><b>
2146 unsigned long <em>flags</em>,
2147           </b></td>
2148         </tr>
2149         <tr>
2150           <td></td>
2151           <td><b>
2152 <a class="el" href="group__dbprim__smat.html#a3">smat_resize_t</a> <em>resize</em>,
2153           </b></td>
2154         </tr>
2155         <tr>
2156           <td></td>
2157           <td><b>
2158 void * <em>extra</em>,
2159           </b></td>
2160         </tr>
2161         <tr>
2162           <td></td>
2163           <td><b>
2164 unsigned long <em>init_mod</em>&nbsp;)
2165           </b></td>
2166         </tr>
2167
2168       </table>
2169     </td>
2170   </tr>
2171 </table>
2172 <table cellspacing=5 cellpadding=0 border=0>
2173   <tr>
2174     <td>
2175       &nbsp;
2176     </td>
2177     <td>
2178
2179 <p>
2180 This function dynamically initializes a sparse matrix table.<dl compact><dt>
2181 <b>Parameters: </b><dd>
2182 <table border=0 cellspacing=2 cellpadding=0>
2183 <tr><td valign=top><em>table</em>
2184 &nbsp;</td><td>
2185 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> to be initialized. </td></tr>
2186 <tr><td valign=top><em>flags</em>
2187 &nbsp;</td><td>
2188 A bit-wise OR of <a class="el" href="group__dbprim__hash.html#a16">HASH_FLAG_AUTOGROW</a> and <a class="el" href="group__dbprim__hash.html#a17">HASH_FLAG_AUTOSHRINK</a>. If neither behavior is desired, use 0. </td></tr>
2189 <tr><td valign=top><em>resize</em>
2190 &nbsp;</td><td>
2191 A <a class="el" href="group__dbprim__hash.html#a5">hash_resize_t</a> function pointer for determining whether resizing is permitted and/or for notification of the resize. </td></tr>
2192 <tr><td valign=top><em>extra</em>
2193 &nbsp;</td><td>
2194 Extra pointer data that should be associated with the sparse matrix table. </td></tr>
2195 <tr><td valign=top><em>init_mod</em>
2196 &nbsp;</td><td>
2197 An initial modulus for the table. This will presumably be extracted by <a class="el" href="group__dbprim__smat.html#a25">st_modulus</a>() in a previous invocation of the application. A 0 value is valid.</td></tr>
2198 </table>
2199 </dl><dl compact><dt>
2200 <b>Return values: </b><dd>
2201 <table border=0 cellspacing=2 cellpadding=0>
2202 <tr><td valign=top><em>DB_ERR_BADARGS</em>
2203 &nbsp;</td><td>
2204 An invalid argument was given. </td></tr>
2205 <tr><td valign=top><em>ENOMEM</em>
2206 &nbsp;</td><td>
2207 Unable to allocate memory. </td></tr>
2208 </table>
2209 </dl>    </td>
2210   </tr>
2211 </table>
2212 <a name="a13" doxytag="st_iter.c::st_iter"></a><p>
2213 <table width="100%" cellpadding="2" cellspacing="0" border="0">
2214   <tr>
2215     <td class="md">
2216       <table cellpadding="0" cellspacing="0" border="0">
2217         <tr>
2218           <td nowrap valign="top"><b>
2219 unsigned long st_iter (
2220           </b></td>
2221           <td valign="bottom"><b>
2222 <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> * <em>table</em>,
2223           </b></td>
2224         </tr>
2225         <tr>
2226           <td></td>
2227           <td><b>
2228 <a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> <em>iter_func</em>,
2229           </b></td>
2230         </tr>
2231         <tr>
2232           <td></td>
2233           <td><b>
2234 void * <em>extra</em>&nbsp;)
2235           </b></td>
2236         </tr>
2237
2238       </table>
2239     </td>
2240   </tr>
2241 </table>
2242 <table cellspacing=5 cellpadding=0 border=0>
2243   <tr>
2244     <td>
2245       &nbsp;
2246     </td>
2247     <td>
2248
2249 <p>
2250
2251 <p>
2252  This function iterates over every entry in a sparse matrix (in an unspecified order), executing the given <code>iter_func</code> on each entry.<dl compact><dt>
2253 <b>Parameters: </b><dd>
2254 <table border=0 cellspacing=2 cellpadding=0>
2255 <tr><td valign=top><em>table</em>
2256 &nbsp;</td><td>
2257 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>. </td></tr>
2258 <tr><td valign=top><em>iter_func</em>
2259 &nbsp;</td><td>
2260 A pointer to a callback function used to perform user-specified actions on an entry in a sparse matrix. <code>NULL</code> is an invalid value. See the documentation for <a class="el" href="group__dbprim__smat.html#a4">smat_iter_t</a> for more information. </td></tr>
2261 <tr><td valign=top><em>extra</em>
2262 &nbsp;</td><td>
2263 A <code>void</code> pointer that will be passed to <code>iter_func</code>.</td></tr>
2264 </table>
2265 </dl><dl compact><dt>
2266 <b>Return values: </b><dd>
2267 <table border=0 cellspacing=2 cellpadding=0>
2268 <tr><td valign=top><em>DB_ERR_BADARGS</em>
2269 &nbsp;</td><td>
2270 An argument was invalid. </td></tr>
2271 <tr><td valign=top><em>DB_ERR_FROZEN</em>
2272 &nbsp;</td><td>
2273 The sparse matrix is frozen. </td></tr>
2274 </table>
2275 </dl>    </td>
2276   </tr>
2277 </table>
2278 <a name="a11" doxytag="st_remove.c::st_remove"></a><p>
2279 <table width="100%" cellpadding="2" cellspacing="0" border="0">
2280   <tr>
2281     <td class="md">
2282       <table cellpadding="0" cellspacing="0" border="0">
2283         <tr>
2284           <td nowrap valign="top"><b>
2285 unsigned long st_remove (
2286           </b></td>
2287           <td valign="bottom"><b>
2288 <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> * <em>table</em>,
2289           </b></td>
2290         </tr>
2291         <tr>
2292           <td></td>
2293           <td><b>
2294 <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> * <em>entry</em>&nbsp;)
2295           </b></td>
2296         </tr>
2297
2298       </table>
2299     </td>
2300   </tr>
2301 </table>
2302 <table cellspacing=5 cellpadding=0 border=0>
2303   <tr>
2304     <td>
2305       &nbsp;
2306     </td>
2307     <td>
2308
2309 <p>
2310
2311 <p>
2312  This function removes the given entry from the specified sparse matrix.<dl compact><dt>
2313 <b>Parameters: </b><dd>
2314 <table border=0 cellspacing=2 cellpadding=0>
2315 <tr><td valign=top><em>table</em>
2316 &nbsp;</td><td>
2317 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>. </td></tr>
2318 <tr><td valign=top><em>entry</em>
2319 &nbsp;</td><td>
2320 A pointer to a <a class="el" href="group__dbprim__smat.html#a2">smat_entry_t</a> to be removed from the table.</td></tr>
2321 </table>
2322 </dl><dl compact><dt>
2323 <b>Return values: </b><dd>
2324 <table border=0 cellspacing=2 cellpadding=0>
2325 <tr><td valign=top><em>DB_ERR_BADARGS</em>
2326 &nbsp;</td><td>
2327 An invalid argument was given. </td></tr>
2328 <tr><td valign=top><em>DB_ERR_WRONGTABLE</em>
2329 &nbsp;</td><td>
2330 Entry is not in this sparse matrix. </td></tr>
2331 <tr><td valign=top><em>DB_ERR_UNRECOVERABLE</em>
2332 &nbsp;</td><td>
2333 An unrecoverable error occurred while removing the entry from the table. </td></tr>
2334 </table>
2335 </dl>    </td>
2336   </tr>
2337 </table>
2338 <a name="a15" doxytag="st_resize.c::st_resize"></a><p>
2339 <table width="100%" cellpadding="2" cellspacing="0" border="0">
2340   <tr>
2341     <td class="md">
2342       <table cellpadding="0" cellspacing="0" border="0">
2343         <tr>
2344           <td nowrap valign="top"><b>
2345 unsigned long st_resize (
2346           </b></td>
2347           <td valign="bottom"><b>
2348 <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a> * <em>table</em>,
2349           </b></td>
2350         </tr>
2351         <tr>
2352           <td></td>
2353           <td><b>
2354 unsigned long <em>new_size</em>&nbsp;)
2355           </b></td>
2356         </tr>
2357
2358       </table>
2359     </td>
2360   </tr>
2361 </table>
2362 <table cellspacing=5 cellpadding=0 border=0>
2363   <tr>
2364     <td>
2365       &nbsp;
2366     </td>
2367     <td>
2368
2369 <p>
2370
2371 <p>
2372  This function resizes the hash table associated with a sparse matrix based on the <code>new_size</code> parameter. See the documentation for <a class="el" href="group__dbprim__hash.html#a13">ht_resize</a>() for more information.<dl compact><dt>
2373 <b>Parameters: </b><dd>
2374 <table border=0 cellspacing=2 cellpadding=0>
2375 <tr><td valign=top><em>table</em>
2376 &nbsp;</td><td>
2377 A pointer to a <a class="el" href="group__dbprim__smat.html#a0">smat_table_t</a>. </td></tr>
2378 <tr><td valign=top><em>new_size</em>
2379 &nbsp;</td><td>
2380 A new size value for the table.</td></tr>
2381 </table>
2382 </dl><dl compact><dt>
2383 <b>Return values: </b><dd>
2384 <table border=0 cellspacing=2 cellpadding=0>
2385 <tr><td valign=top><em>DB_ERR_BADARGS</em>
2386 &nbsp;</td><td>
2387 An argument was invalid. </td></tr>
2388 <tr><td valign=top><em>DB_ERR_FROZEN</em>
2389 &nbsp;</td><td>
2390 The table is currently frozen. </td></tr>
2391 <tr><td valign=top><em>DB_ERR_UNRECOVERABLE</em>
2392 &nbsp;</td><td>
2393 A catastrophic error was encountered. The table is now unusable. </td></tr>
2394 <tr><td valign=top><em>ENOMEM</em>
2395 &nbsp;</td><td>
2396 No memory could be allocated for the new bucket table. </td></tr>
2397 </table>
2398 </dl>    </td>
2399   </tr>
2400 </table>
2401 <hr><address><small>Generated at Thu Mar 6 21:23:10 2003 for dbprim by
2402 <a href="http://www.doxygen.org/index.html">
2403 <img src="doxygen.gif" alt="doxygen" align="middle" border=0
2404 width=110 height=53></a>1.2.8.1 written by <a href="mailto:dimitri@stack.nl">Dimitri van Heesch</a>,
2405  &copy;&nbsp;1997-2001</small></address>
2406 </body>
2407 </html>