libs/dbprim/doc/latex/group__dbprim__smat.tex

   1 \section{Sparse matrices}
   2 \label{group__dbprim__smat}\index{Sparse matrices@{Sparse matrices}}
   3 Operations for sparse matrices.
   4 \subsection*{Defines}
   5 \begin{CompactItemize}
   6 \item
   7 \#define {\bf SMAT\_\-TABLE\_\-INIT}(flags, resize, extra)
   8 \begin{CompactList}\small\item\em Sparse matrix table static initializer.\item\end{CompactList}\item
   9 \#define {\bf st\_\-verify}(table)
  10 \begin{CompactList}\small\item\em Sparse matrix table verification macro.\item\end{CompactList}\item
  11 \#define {\bf st\_\-flags}(table)
  12 \begin{CompactList}\small\item\em Sparse matrix table flags.\item\end{CompactList}\item
  13 \#define {\bf st\_\-frozen}(table)
  14 \begin{CompactList}\small\item\em Determine if a sparse matrix is frozen.\item\end{CompactList}\item
  15 \#define {\bf st\_\-modulus}(table)
  16 \begin{CompactList}\small\item\em Sparse matrix table modulus.\item\end{CompactList}\item
  17 \#define {\bf st\_\-count}(table)
  18 \begin{CompactList}\small\item\em Sparse matrix table count.\item\end{CompactList}\item
  19 \#define {\bf st\_\-extra}(table)
  20 \begin{CompactList}\small\item\em Extra pointer data in a sparse matrix table.\item\end{CompactList}\item
  21 \#define {\bf st\_\-size}(table)
  22 \begin{CompactList}\small\item\em Sparse matrix table memory size.\item\end{CompactList}\item
  23 \#define {\bf SMAT\_\-HEAD\_\-INIT}(elem, object)
  24 \begin{CompactList}\small\item\em Sparse matrix list head static initializer.\item\end{CompactList}\item
  25 \#define {\bf sh\_\-verify}(head)
  26 \begin{CompactList}\small\item\em Sparse matrix list head verification macro.\item\end{CompactList}\item
  27 \#define {\bf sh\_\-elem}(head)
  28 \begin{CompactList}\small\item\em Sparse matrix list head element macro.\item\end{CompactList}\item
  29 \#define {\bf sh\_\-table}(head)
  30 \begin{CompactList}\small\item\em Sparse matrix list head table pointer.\item\end{CompactList}\item
  31 \#define {\bf sh\_\-frozen}(head)
  32 \begin{CompactList}\small\item\em Determine if a sparse matrix is frozen.\item\end{CompactList}\item
  33 \#define {\bf sh\_\-count}(head)
  34 \begin{CompactList}\small\item\em Sparse matrix list count.\item\end{CompactList}\item
  35 \#define {\bf sh\_\-first}(head)
  36 \begin{CompactList}\small\item\em First element in sparse matrix list.\item\end{CompactList}\item
  37 \#define {\bf sh\_\-last}(head)
  38 \begin{CompactList}\small\item\em Last element in sparse matrix list.\item\end{CompactList}\item
  39 \#define {\bf sh\_\-object}(head)
  40 \begin{CompactList}\small\item\em Object represented by a sparse matrix list head.\item\end{CompactList}\item
  41 \#define {\bf sh\_\-size}(head)
  42 \begin{CompactList}\small\item\em Sparse matrix list memory size.\item\end{CompactList}\item
  43 \#define {\bf se\_\-verify}(entry)
  44 \begin{CompactList}\small\item\em Sparse matrix entry verification macro.\item\end{CompactList}\item
  45 \#define {\bf se\_\-table}(entry)
  46 \begin{CompactList}\small\item\em Sparse matrix entry table.\item\end{CompactList}\item
  47 \#define {\bf \_\-se\_\-link}(entry)
  48 \begin{CompactList}\small\item\em Sparse matrix entry linked list element.\item\end{CompactList}\item
  49 \#define {\bf se\_\-flags}(entry)
  50 \begin{CompactList}\small\item\em Sparse matrix entry flags.\item\end{CompactList}\item
  51 \#define {\bf se\_\-hash}(entry)
  52 \begin{CompactList}\small\item\em Sparse matrix table entry hash value.\item\end{CompactList}\item
  53 \#define {\bf se\_\-next}(entry, n)
  54 \begin{CompactList}\small\item\em Next element in sparse matrix list.\item\end{CompactList}\item
  55 \#define {\bf se\_\-prev}(entry, n)
  56 \begin{CompactList}\small\item\em Previous element in sparse matrix list.\item\end{CompactList}\item
  57 \#define {\bf se\_\-lflags}(entry, n)
  58 \begin{CompactList}\small\item\em Flags associated with an entry in a sparse matrix list.\item\end{CompactList}\item
  59 \#define {\bf se\_\-object}(entry, n)
  60 \begin{CompactList}\small\item\em Object associated with an entry in a sparse matrix list.\item\end{CompactList}\end{CompactItemize}
  61 \subsection*{Typedefs}
  62 \begin{CompactItemize}
  63 \item
  64 typedef struct \_\-smat\_\-table\_\-s {\bf smat\_\-table\_\-t}
  65 \begin{CompactList}\small\item\em Sparse matrix table.\item\end{CompactList}\item
  66 typedef struct \_\-smat\_\-head\_\-s {\bf smat\_\-head\_\-t}
  67 \begin{CompactList}\small\item\em Sparse matrix list head.\item\end{CompactList}\item
  68 typedef struct \_\-smat\_\-entry\_\-s {\bf smat\_\-entry\_\-t}
  69 \begin{CompactList}\small\item\em Sparse matrix entry.\item\end{CompactList}\item
  70 typedef unsigned long ($\ast$ {\bf smat\_\-resize\_\-t} )({\bf smat\_\-table\_\-t} $\ast$, unsigned long)
  71 \begin{CompactList}\small\item\em Sparse matrix table resize callback.\item\end{CompactList}\item
  72 typedef unsigned long ($\ast$ {\bf smat\_\-iter\_\-t} )({\bf smat\_\-table\_\-t} $\ast$, {\bf smat\_\-entry\_\-t} $\ast$, void $\ast$)
  73 \begin{CompactList}\small\item\em Sparse matrix iteration callback.\item\end{CompactList}\item
  74 typedef unsigned long ($\ast$ {\bf smat\_\-comp\_\-t} )({\bf db\_\-key\_\-t} $\ast$, {\bf smat\_\-entry\_\-t} $\ast$)
  75 \begin{CompactList}\small\item\em Sparse matrix comparison callback.\item\end{CompactList}\item
  76 typedef enum {\bf \_\-smat\_\-loc\_\-e} {\bf smat\_\-loc\_\-t}
  77 \begin{CompactList}\small\item\em Sparse matrix location.\item\end{CompactList}\end{CompactItemize}
  78 \subsection*{Enumerations}
  79 \begin{CompactItemize}
  80 \item
  81 enum {\bf \_\-smat\_\-loc\_\-e} \{ {\bf SMAT\_\-LOC\_\-FIRST},
  82 {\bf SMAT\_\-LOC\_\-SECOND}
  83  \}
  84 \begin{CompactList}\small\item\em Sparse matrix location.\item\end{CompactList}\end{CompactItemize}
  85 \subsection*{Functions}
  86 \begin{CompactItemize}
  87 \item
  88 unsigned long {\bf smat\_\-cleanup} (void)
  89 \begin{CompactList}\small\item\em Clean up the smat free list.\item\end{CompactList}\item
  90 unsigned long {\bf smat\_\-freemem} (void)
  91 \begin{CompactList}\small\item\em Report how much memory is used by the free list.\item\end{CompactList}\item
  92 unsigned long {\bf st\_\-init} ({\bf smat\_\-table\_\-t} $\ast$table, unsigned long flags, {\bf smat\_\-resize\_\-t} resize, void $\ast$extra, unsigned long init\_\-mod)
  93 \item
  94 unsigned long {\bf st\_\-add} ({\bf smat\_\-table\_\-t} $\ast$table, {\bf smat\_\-entry\_\-t} $\ast$$\ast$entry\_\-p, {\bf smat\_\-head\_\-t} $\ast$head1, {\bf link\_\-loc\_\-t} loc1, {\bf smat\_\-entry\_\-t} $\ast$ent1, {\bf smat\_\-head\_\-t} $\ast$head2, {\bf link\_\-loc\_\-t} loc2, {\bf smat\_\-entry\_\-t} $\ast$ent2)
  95 \begin{CompactList}\small\item\em Add an entry to a sparse matrix.\item\end{CompactList}\item
  96 unsigned long {\bf st\_\-remove} ({\bf smat\_\-table\_\-t} $\ast$table, {\bf smat\_\-entry\_\-t} $\ast$entry)
  97 \begin{CompactList}\small\item\em Remove an entry from a sparse matrix.\item\end{CompactList}\item
  98 unsigned long {\bf st\_\-find} ({\bf smat\_\-table\_\-t} $\ast$table, {\bf smat\_\-entry\_\-t} $\ast$$\ast$entry\_\-p, {\bf smat\_\-head\_\-t} $\ast$head1, {\bf smat\_\-head\_\-t} $\ast$head2)
  99 \begin{CompactList}\small\item\em Find an entry in a sparse matrix.\item\end{CompactList}\item
 100 unsigned long {\bf st\_\-iter} ({\bf smat\_\-table\_\-t} $\ast$table, {\bf smat\_\-iter\_\-t} iter\_\-func, void $\ast$extra)
 101 \begin{CompactList}\small\item\em Iterate over each entry in a sparse matrix.\item\end{CompactList}\item
 102 unsigned long {\bf st\_\-flush} ({\bf smat\_\-table\_\-t} $\ast$table, {\bf smat\_\-iter\_\-t} flush\_\-func, void $\ast$extra)
 103 \begin{CompactList}\small\item\em Flush a sparse matrix.\item\end{CompactList}\item
 104 unsigned long {\bf st\_\-resize} ({\bf smat\_\-table\_\-t} $\ast$table, unsigned long new\_\-size)
 105 \begin{CompactList}\small\item\em Resize a sparse matrix table.\item\end{CompactList}\item
 106 unsigned long {\bf st\_\-free} ({\bf smat\_\-table\_\-t} $\ast$table)
 107 \begin{CompactList}\small\item\em Free memory used by an empty sparse matrix table.\item\end{CompactList}\item
 108 unsigned long {\bf sh\_\-init} ({\bf smat\_\-head\_\-t} $\ast$head, {\bf smat\_\-loc\_\-t} elem, void $\ast$object)
 109 \begin{CompactList}\small\item\em Dynamically initialize a sparse matrix row or column head.\item\end{CompactList}\item
 110 unsigned long {\bf sh\_\-move} ({\bf smat\_\-head\_\-t} $\ast$head, {\bf smat\_\-entry\_\-t} $\ast$elem, {\bf link\_\-loc\_\-t} loc, {\bf smat\_\-entry\_\-t} $\ast$elem2)
 111 \begin{CompactList}\small\item\em Move an entry within a row or column list.\item\end{CompactList}\item
 112 unsigned long {\bf sh\_\-find} ({\bf smat\_\-head\_\-t} $\ast$head, {\bf smat\_\-entry\_\-t} $\ast$$\ast$elem\_\-p, {\bf smat\_\-comp\_\-t} comp\_\-func, {\bf smat\_\-entry\_\-t} $\ast$start, {\bf db\_\-key\_\-t} $\ast$key)
 113 \begin{CompactList}\small\item\em Find an entry in a row or column of a sparse matrix.\item\end{CompactList}\item
 114 unsigned long {\bf sh\_\-iter} ({\bf smat\_\-head\_\-t} $\ast$head, {\bf smat\_\-iter\_\-t} iter\_\-func, void $\ast$extra)
 115 \begin{CompactList}\small\item\em Iterate over each entry in a row or column of a sparse matrix.\item\end{CompactList}\end{CompactItemize}
 116
 117
 118 \subsection{Detailed Description}
 119 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.
 120
 121 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.
 122
 123 Because sparse matrices are so complicated, there are three structures and a variety of operations used. Two of the structures, {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})} and {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}, are caller-allocated. However, the third structure, {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}, 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 {\bf smat\_\-cleanup}() {\rm (p.\,\pageref{group__dbprim__smat_a7})} and {\bf smat\_\-freemem}() {\rm (p.\,\pageref{group__dbprim__smat_a8})} calls.
 124
 125 The {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})} contains the hash table. Only one of these need be allocated per type of association--for instance, in the above example, only one {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})} needs to be allocated to represent the manager-employee relationship.
 126
 127 The {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})} contains the linked list. There are actually two kinds of these structures--one is {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})}, which could be regarded as a ``row,'' and the other is {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})}, 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 {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})} for a manager may be {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})}, and one for an employee must then be {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})}. (These values are set when initializing the {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})} structure.)
 128
 129 An association may be created with the {\bf st\_\-add}() {\rm (p.\,\pageref{group__dbprim__smat_a10})} 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 {\bf st\_\-remove}() {\rm (p.\,\pageref{group__dbprim__smat_a11})}, or looked up with {\bf st\_\-find}() {\rm (p.\,\pageref{group__dbprim__smat_a12})}. If iteration over all associations is desired, use the {\bf st\_\-iter}() {\rm (p.\,\pageref{group__dbprim__smat_a13})} function. Removing all associations from a table may be performed with {\bf st\_\-flush}() {\rm (p.\,\pageref{group__dbprim__smat_a14})}, which optionally calls a user-defined clean-up function. The associated hash table may be resized with {\bf st\_\-resize}() {\rm (p.\,\pageref{group__dbprim__smat_a15})}, and the bucket table may be released with {\bf st\_\-free}() {\rm (p.\,\pageref{group__dbprim__smat_a16})}.
 130
 131 An association may also be reordered within the linked lists using the {\bf sh\_\-move}() {\rm (p.\,\pageref{group__dbprim__smat_a18})} function. If a particular entry is desired, use the {\bf sh\_\-find}() {\rm (p.\,\pageref{group__dbprim__smat_a19})} function with a user-defined comparison function to locate it. Iteration may be performed with the {\bf sh\_\-iter}() {\rm (p.\,\pageref{group__dbprim__smat_a20})} 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.
 132
 133 \subsection{Define Documentation}
 134 \index{dbprim_smat@{dbprim\_\-smat}!SMAT_HEAD_INIT@{SMAT\_\-HEAD\_\-INIT}}
 135 \index{SMAT_HEAD_INIT@{SMAT\_\-HEAD\_\-INIT}!dbprim_smat@{dbprim\_\-smat}}
 136 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define SMAT\_\-HEAD\_\-INIT(elem, object)}\label{group__dbprim__smat_a29}
 137
 138
 139
 140
 141  This macro statically initializes a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.\begin{Desc}
 142 \item[{\bf Parameters: }]\par
 143 \begin{description}
 144 \item[
 145 {\em elem}]One of {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})} or {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})} specifing whether the object is a member of the set of rows or columns. \item[
 146 {\em object}]A pointer to {\tt void} representing the object associated with the list head. \end{description}
 147 \end{Desc}
 148 \index{dbprim_smat@{dbprim\_\-smat}!SMAT_TABLE_INIT@{SMAT\_\-TABLE\_\-INIT}}
 149 \index{SMAT_TABLE_INIT@{SMAT\_\-TABLE\_\-INIT}!dbprim_smat@{dbprim\_\-smat}}
 150 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define SMAT\_\-TABLE\_\-INIT(flags, resize, extra)}\label{group__dbprim__smat_a21}
 151
 152
 153
 154
 155  This macro statically initializes a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.\begin{Desc}
 156 \item[{\bf Parameters: }]\par
 157 \begin{description}
 158 \item[
 159 {\em flags}]A bit-wise OR of {\bf HASH\_\-FLAG\_\-AUTOGROW} {\rm (p.\,\pageref{group__dbprim__hash_a16})} and {\bf HASH\_\-FLAG\_\-AUTOSHRINK} {\rm (p.\,\pageref{group__dbprim__hash_a17})}. If neither behavior is desired, use 0. \item[
 160 {\em resize}]A {\bf smat\_\-resize\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a3})} function pointer for determining whether resizing is permitted and/or for notification of the resize. \item[
 161 {\em extra}]Extra pointer data that should be associated with the sparse matrix. \end{description}
 162 \end{Desc}
 163 \index{dbprim_smat@{dbprim\_\-smat}!_se_link@{\_\-se\_\-link}}
 164 \index{_se_link@{\_\-se\_\-link}!dbprim_smat@{dbprim\_\-smat}}
 165 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define \_\-se\_\-link(entry)}\label{group__dbprim__smat_a41}
 166
 167
 168
 169
 170 For internal use only.\index{dbprim_smat@{dbprim\_\-smat}!se_flags@{se\_\-flags}}
 171 \index{se_flags@{se\_\-flags}!dbprim_smat@{dbprim\_\-smat}}
 172 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define se\_\-flags(entry)}\label{group__dbprim__smat_a42}
 173
 174
 175
 176
 177  This macro retrieves a set of user-defined flags associated with the entry. It may be used as an lvalue to set those flags.\begin{Desc}
 178 \item[{\bf Parameters: }]\par
 179 \begin{description}
 180 \item[
 181 {\em entry}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}.
 182
 183 \end{description}
 184 \end{Desc}
 185 \begin{Desc}
 186 \item[{\bf Returns: }]\par
 187 An {\tt unsigned long} containing the flags associated with the entry. \end{Desc}
 188 \index{dbprim_smat@{dbprim\_\-smat}!se_hash@{se\_\-hash}}
 189 \index{se_hash@{se\_\-hash}!dbprim_smat@{dbprim\_\-smat}}
 190 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define se\_\-hash(entry)}\label{group__dbprim__smat_a43}
 191
 192
 193
 194
 195  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.\begin{Desc}
 196 \item[{\bf Parameters: }]\par
 197 \begin{description}
 198 \item[
 199 {\em entry}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}.
 200
 201 \end{description}
 202 \end{Desc}
 203 \begin{Desc}
 204 \item[{\bf Returns: }]\par
 205 An {\tt unsigned long} containing the hash code for the entry. \end{Desc}
 206 \index{dbprim_smat@{dbprim\_\-smat}!se_lflags@{se\_\-lflags}}
 207 \index{se_lflags@{se\_\-lflags}!dbprim_smat@{dbprim\_\-smat}}
 208 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define se\_\-lflags(entry, n)}\label{group__dbprim__smat_a46}
 209
 210
 211
 212
 213  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.\begin{Desc}
 214 \item[{\bf Parameters: }]\par
 215 \begin{description}
 216 \item[
 217 {\em entry}]A pointer to {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. \item[
 218 {\em n}]One of {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})} or {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})} to specify which list thread is desired.
 219
 220 \end{description}
 221 \end{Desc}
 222 \begin{Desc}
 223 \item[{\bf Returns: }]\par
 224 An {\tt unsigned long} containing the flags associated with the entry. \end{Desc}
 225 \index{dbprim_smat@{dbprim\_\-smat}!se_next@{se\_\-next}}
 226 \index{se_next@{se\_\-next}!dbprim_smat@{dbprim\_\-smat}}
 227 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define se\_\-next(entry, n)}\label{group__dbprim__smat_a44}
 228
 229
 230
 231
 232  This macro retrieves a pointer to the {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} for the next element in the sparse matrix list.
 233
 234 \begin{Desc}
 235 \item[{\bf Warning: }]\par
 236 This macro may evaluate the {\tt entry} and {\tt n} arguments twice.\end{Desc}
 237 \begin{Desc}
 238 \item[{\bf Parameters: }]\par
 239 \begin{description}
 240 \item[
 241 {\em entry}]A pointer to {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. \item[
 242 {\em n}]One of {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})} or {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})} to specify which list thread is desired.
 243
 244 \end{description}
 245 \end{Desc}
 246 \begin{Desc}
 247 \item[{\bf Returns: }]\par
 248 A pointer to {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. \end{Desc}
 249 \index{dbprim_smat@{dbprim\_\-smat}!se_object@{se\_\-object}}
 250 \index{se_object@{se\_\-object}!dbprim_smat@{dbprim\_\-smat}}
 251 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define se\_\-object(entry, n)}\label{group__dbprim__smat_a47}
 252
 253
 254
 255
 256  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.\begin{Desc}
 257 \item[{\bf Parameters: }]\par
 258 \begin{description}
 259 \item[
 260 {\em entry}]A pointer to {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. \item[
 261 {\em n}]One of {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})} or {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})} to specify which list thread is desired.
 262
 263 \end{description}
 264 \end{Desc}
 265 \begin{Desc}
 266 \item[{\bf Returns: }]\par
 267 A pointer to {\tt void} representing the object. \end{Desc}
 268 \index{dbprim_smat@{dbprim\_\-smat}!se_prev@{se\_\-prev}}
 269 \index{se_prev@{se\_\-prev}!dbprim_smat@{dbprim\_\-smat}}
 270 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define se\_\-prev(entry, n)}\label{group__dbprim__smat_a45}
 271
 272
 273
 274
 275  This macro retrieves a pointer to the {\bf link\_\-elem\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a1})} for the previous element in the sparse matrix list.
 276
 277 \begin{Desc}
 278 \item[{\bf Warning: }]\par
 279 This macro may evaluate the {\tt entry} and {\tt n} arguments twice.\end{Desc}
 280 \begin{Desc}
 281 \item[{\bf Parameters: }]\par
 282 \begin{description}
 283 \item[
 284 {\em entry}]A pointer to {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. \item[
 285 {\em n}]One of {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})} or {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})} to specify which list thread is desired.
 286
 287 \end{description}
 288 \end{Desc}
 289 \begin{Desc}
 290 \item[{\bf Returns: }]\par
 291 A pointer to {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. \end{Desc}
 292 \index{dbprim_smat@{dbprim\_\-smat}!se_table@{se\_\-table}}
 293 \index{se_table@{se\_\-table}!dbprim_smat@{dbprim\_\-smat}}
 294 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define se\_\-table(entry)}\label{group__dbprim__smat_a40}
 295
 296
 297
 298
 299  This macro retrieves a pointer to the table that the sparse matrix entry is in.\begin{Desc}
 300 \item[{\bf Parameters: }]\par
 301 \begin{description}
 302 \item[
 303 {\em entry}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}.
 304
 305 \end{description}
 306 \end{Desc}
 307 \begin{Desc}
 308 \item[{\bf Returns: }]\par
 309 A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}. \end{Desc}
 310 \index{dbprim_smat@{dbprim\_\-smat}!se_verify@{se\_\-verify}}
 311 \index{se_verify@{se\_\-verify}!dbprim_smat@{dbprim\_\-smat}}
 312 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define se\_\-verify(entry)}\label{group__dbprim__smat_a39}
 313
 314
 315
 316
 317  This macro verifies that a given pointer actually does point to a sparse matrix entry.\begin{Desc}
 318 \item[{\bf Parameters: }]\par
 319 \begin{description}
 320 \item[
 321 {\em entry}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}.
 322
 323 \end{description}
 324 \end{Desc}
 325 \begin{Desc}
 326 \item[{\bf Returns: }]\par
 327 Boolean true if {\tt entry} is a valid sparse matrix entry or false otherwise. \end{Desc}
 328 \index{dbprim_smat@{dbprim\_\-smat}!sh_count@{sh\_\-count}}
 329 \index{sh_count@{sh\_\-count}!dbprim_smat@{dbprim\_\-smat}}
 330 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define sh\_\-count(head)}\label{group__dbprim__smat_a34}
 331
 332
 333
 334
 335  This macro retrieves the number of elements in the sparse matrix list rooted at {\tt head}.\begin{Desc}
 336 \item[{\bf Parameters: }]\par
 337 \begin{description}
 338 \item[
 339 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
 340
 341 \end{description}
 342 \end{Desc}
 343 \begin{Desc}
 344 \item[{\bf Returns: }]\par
 345 An {\tt unsigned long} containing a count of the number of elements in the sparse matrix list. \end{Desc}
 346 \index{dbprim_smat@{dbprim\_\-smat}!sh_elem@{sh\_\-elem}}
 347 \index{sh_elem@{sh\_\-elem}!dbprim_smat@{dbprim\_\-smat}}
 348 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define sh\_\-elem(head)}\label{group__dbprim__smat_a31}
 349
 350
 351
 352
 353  This macro retrieves the position indicator for the sparse matrix head. It will return one of {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})} or {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})}.\begin{Desc}
 354 \item[{\bf Parameters: }]\par
 355 \begin{description}
 356 \item[
 357 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
 358
 359 \end{description}
 360 \end{Desc}
 361 \begin{Desc}
 362 \item[{\bf Returns: }]\par
 363 An {\bf smat\_\-loc\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a6})}. \end{Desc}
 364 \index{dbprim_smat@{dbprim\_\-smat}!sh_first@{sh\_\-first}}
 365 \index{sh_first@{sh\_\-first}!dbprim_smat@{dbprim\_\-smat}}
 366 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define sh\_\-first(head)}\label{group__dbprim__smat_a35}
 367
 368
 369
 370
 371  This macro retrieves a pointer to the {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} for the first element in the sparse matrix list.
 372
 373 \begin{Desc}
 374 \item[{\bf Warning: }]\par
 375 This macro may evaluate the {\tt head} argument twice.\end{Desc}
 376 \begin{Desc}
 377 \item[{\bf Parameters: }]\par
 378 \begin{description}
 379 \item[
 380 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
 381
 382 \end{description}
 383 \end{Desc}
 384 \begin{Desc}
 385 \item[{\bf Returns: }]\par
 386 A pointer to {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. \end{Desc}
 387 \index{dbprim_smat@{dbprim\_\-smat}!sh_frozen@{sh\_\-frozen}}
 388 \index{sh_frozen@{sh\_\-frozen}!dbprim_smat@{dbprim\_\-smat}}
 389 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define sh\_\-frozen(head)}\label{group__dbprim__smat_a33}
 390
 391
 392
 393
 394  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.\begin{Desc}
 395 \item[{\bf Parameters: }]\par
 396 \begin{description}
 397 \item[
 398 {\em head}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
 399
 400 \end{description}
 401 \end{Desc}
 402 \begin{Desc}
 403 \item[{\bf Returns: }]\par
 404 A zero value if the matrix is not frozen or a non-zero value if the matrix is frozen. \end{Desc}
 405 \index{dbprim_smat@{dbprim\_\-smat}!sh_last@{sh\_\-last}}
 406 \index{sh_last@{sh\_\-last}!dbprim_smat@{dbprim\_\-smat}}
 407 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define sh\_\-last(head)}\label{group__dbprim__smat_a36}
 408
 409
 410
 411
 412  This macro retrieves a pointer to the {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} for the last element in the sparse matrix list.
 413
 414 \begin{Desc}
 415 \item[{\bf Warning: }]\par
 416 This macro may evaluate the {\tt head} argument twice.\end{Desc}
 417 \begin{Desc}
 418 \item[{\bf Parameters: }]\par
 419 \begin{description}
 420 \item[
 421 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
 422
 423 \end{description}
 424 \end{Desc}
 425 \begin{Desc}
 426 \item[{\bf Returns: }]\par
 427 A pointer to {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. \end{Desc}
 428 \index{dbprim_smat@{dbprim\_\-smat}!sh_object@{sh\_\-object}}
 429 \index{sh_object@{sh\_\-object}!dbprim_smat@{dbprim\_\-smat}}
 430 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define sh\_\-object(head)}\label{group__dbprim__smat_a37}
 431
 432
 433
 434
 435  This macro retrieves a pointer to the object referenced by the sparse matrix list head.\begin{Desc}
 436 \item[{\bf Parameters: }]\par
 437 \begin{description}
 438 \item[
 439 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
 440
 441 \end{description}
 442 \end{Desc}
 443 \begin{Desc}
 444 \item[{\bf Returns: }]\par
 445 A pointer to {\tt void}. \end{Desc}
 446 \index{dbprim_smat@{dbprim\_\-smat}!sh_size@{sh\_\-size}}
 447 \index{sh_size@{sh\_\-size}!dbprim_smat@{dbprim\_\-smat}}
 448 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define sh\_\-size(head)}\label{group__dbprim__smat_a38}
 449
 450
 451
 452
 453  This macro returns the physical size of the memory allocated by the library for this sparse matrix list.
 454
 455 \begin{Desc}
 456 \item[{\bf Note: }]\par
 457 The {\bf st\_\-size}() {\rm (p.\,\pageref{group__dbprim__smat_a28})} macro already counts the memory for each list in the table. Summing the results of {\bf sh\_\-size}() {\rm (p.\,\pageref{group__dbprim__smat_a38})} and {\bf st\_\-size}() {\rm (p.\,\pageref{group__dbprim__smat_a28})} will over-count the amount of memory actually in use.\end{Desc}
 458 \begin{Desc}
 459 \item[{\bf Parameters: }]\par
 460 \begin{description}
 461 \item[
 462 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
 463
 464 \end{description}
 465 \end{Desc}
 466 \begin{Desc}
 467 \item[{\bf Returns: }]\par
 468 A {\tt size\_\-t}. \end{Desc}
 469 \index{dbprim_smat@{dbprim\_\-smat}!sh_table@{sh\_\-table}}
 470 \index{sh_table@{sh\_\-table}!dbprim_smat@{dbprim\_\-smat}}
 471 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define sh\_\-table(head)}\label{group__dbprim__smat_a32}
 472
 473
 474
 475
 476  If there are any elements in this sparse matrix list head, this macro will retrieve a pointer to the table in which they reside.\begin{Desc}
 477 \item[{\bf Parameters: }]\par
 478 \begin{description}
 479 \item[
 480 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
 481
 482 \end{description}
 483 \end{Desc}
 484 \begin{Desc}
 485 \item[{\bf Returns: }]\par
 486 A pointer to {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}. \end{Desc}
 487 \index{dbprim_smat@{dbprim\_\-smat}!sh_verify@{sh\_\-verify}}
 488 \index{sh_verify@{sh\_\-verify}!dbprim_smat@{dbprim\_\-smat}}
 489 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define sh\_\-verify(head)}\label{group__dbprim__smat_a30}
 490
 491
 492
 493
 494  This macro verifies that a given pointer actually does point to a sparse matrix head.\begin{Desc}
 495 \item[{\bf Parameters: }]\par
 496 \begin{description}
 497 \item[
 498 {\em head}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
 499
 500 \end{description}
 501 \end{Desc}
 502 \begin{Desc}
 503 \item[{\bf Returns: }]\par
 504 Boolean true if {\tt head} is a valid sparse matrix head or false otherwise. \end{Desc}
 505 \index{dbprim_smat@{dbprim\_\-smat}!st_count@{st\_\-count}}
 506 \index{st_count@{st\_\-count}!dbprim_smat@{dbprim\_\-smat}}
 507 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define st\_\-count(table)}\label{group__dbprim__smat_a26}
 508
 509
 510
 511
 512  This macro retrieves the total number of items actually in the sparse matrix table.\begin{Desc}
 513 \item[{\bf Parameters: }]\par
 514 \begin{description}
 515 \item[
 516 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
 517
 518 \end{description}
 519 \end{Desc}
 520 \begin{Desc}
 521 \item[{\bf Returns: }]\par
 522 An {\tt unsigned long} containing a count of the number of items in the sparse matrix table. \end{Desc}
 523 \index{dbprim_smat@{dbprim\_\-smat}!st_extra@{st\_\-extra}}
 524 \index{st_extra@{st\_\-extra}!dbprim_smat@{dbprim\_\-smat}}
 525 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define st\_\-extra(table)}\label{group__dbprim__smat_a27}
 526
 527
 528
 529
 530  This macro retrieves the extra pointer data associated with a particular sparse matrix table.\begin{Desc}
 531 \item[{\bf Parameters: }]\par
 532 \begin{description}
 533 \item[
 534 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
 535
 536 \end{description}
 537 \end{Desc}
 538 \begin{Desc}
 539 \item[{\bf Returns: }]\par
 540 A pointer to {\tt void}. \end{Desc}
 541 \index{dbprim_smat@{dbprim\_\-smat}!st_flags@{st\_\-flags}}
 542 \index{st_flags@{st\_\-flags}!dbprim_smat@{dbprim\_\-smat}}
 543 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define st\_\-flags(table)}\label{group__dbprim__smat_a23}
 544
 545
 546
 547
 548  This macro retrieves the flags associated with the sparse matrix table. Only {\bf HASH\_\-FLAG\_\-AUTOGROW} {\rm (p.\,\pageref{group__dbprim__hash_a16})} and {\bf HASH\_\-FLAG\_\-AUTOSHRINK} {\rm (p.\,\pageref{group__dbprim__hash_a17})} 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.\begin{Desc}
 549 \item[{\bf Parameters: }]\par
 550 \begin{description}
 551 \item[
 552 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
 553
 554 \end{description}
 555 \end{Desc}
 556 \begin{Desc}
 557 \item[{\bf Returns: }]\par
 558 An {\tt unsigned long} containing the flags for the sparse matrix table. \end{Desc}
 559 \index{dbprim_smat@{dbprim\_\-smat}!st_frozen@{st\_\-frozen}}
 560 \index{st_frozen@{st\_\-frozen}!dbprim_smat@{dbprim\_\-smat}}
 561 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define st\_\-frozen(table)}\label{group__dbprim__smat_a24}
 562
 563
 564
 565
 566  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.\begin{Desc}
 567 \item[{\bf Parameters: }]\par
 568 \begin{description}
 569 \item[
 570 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
 571
 572 \end{description}
 573 \end{Desc}
 574 \begin{Desc}
 575 \item[{\bf Returns: }]\par
 576 A zero value if the matrix is not frozen or a non-zero value if the matrix is frozen. \end{Desc}
 577 \index{dbprim_smat@{dbprim\_\-smat}!st_modulus@{st\_\-modulus}}
 578 \index{st_modulus@{st\_\-modulus}!dbprim_smat@{dbprim\_\-smat}}
 579 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define st\_\-modulus(table)}\label{group__dbprim__smat_a25}
 580
 581
 582
 583
 584  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.\begin{Desc}
 585 \item[{\bf Parameters: }]\par
 586 \begin{description}
 587 \item[
 588 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
 589
 590 \end{description}
 591 \end{Desc}
 592 \begin{Desc}
 593 \item[{\bf Returns: }]\par
 594 An {\tt unsigned long} containing the number of buckets allocated for the sparse matrix table. \end{Desc}
 595 \index{dbprim_smat@{dbprim\_\-smat}!st_size@{st\_\-size}}
 596 \index{st_size@{st\_\-size}!dbprim_smat@{dbprim\_\-smat}}
 597 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define st\_\-size(table)}\label{group__dbprim__smat_a28}
 598
 599
 600
 601
 602  This macro returns the physical size of the memory allocated by the library for this sparse matrix table.
 603
 604 \begin{Desc}
 605 \item[{\bf Note: }]\par
 606 The {\bf st\_\-size}() {\rm (p.\,\pageref{group__dbprim__smat_a28})} macro already counts the memory for each list in the table. Summing the results of {\bf sh\_\-size}() {\rm (p.\,\pageref{group__dbprim__smat_a38})} and {\bf st\_\-size}() {\rm (p.\,\pageref{group__dbprim__smat_a28})} will over-count the amount of memory actually in use.\end{Desc}
 607 \begin{Desc}
 608 \item[{\bf Parameters: }]\par
 609 \begin{description}
 610 \item[
 611 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
 612
 613 \end{description}
 614 \end{Desc}
 615 \begin{Desc}
 616 \item[{\bf Returns: }]\par
 617 A {\tt size\_\-t}. \end{Desc}
 618 \index{dbprim_smat@{dbprim\_\-smat}!st_verify@{st\_\-verify}}
 619 \index{st_verify@{st\_\-verify}!dbprim_smat@{dbprim\_\-smat}}
 620 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define st\_\-verify(table)}\label{group__dbprim__smat_a22}
 621
 622
 623
 624
 625  This macro verifies that a given pointer actually does point to a sparse matrix table.\begin{Desc}
 626 \item[{\bf Parameters: }]\par
 627 \begin{description}
 628 \item[
 629 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
 630
 631 \end{description}
 632 \end{Desc}
 633 \begin{Desc}
 634 \item[{\bf Returns: }]\par
 635 Boolean true if {\tt table} is a valid sparse matrix table or false otherwise. \end{Desc}
 636
 637
 638 \subsection{Typedef Documentation}
 639 \index{dbprim_smat@{dbprim\_\-smat}!smat_comp_t@{smat\_\-comp\_\-t}}
 640 \index{smat_comp_t@{smat\_\-comp\_\-t}!dbprim_smat@{dbprim\_\-smat}}
 641 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef unsigned long($\ast$ smat\_\-comp\_\-t)({\bf db\_\-key\_\-t} $\ast$, {\bf smat\_\-entry\_\-t} $\ast$)}\label{group__dbprim__smat_a5}
 642
 643
 644
 645
 646  This function pointer references a callback used by {\bf sh\_\-find}() {\rm (p.\,\pageref{group__dbprim__smat_a19})}. It should return 0 if the sparse matrix entry represented by the second argument matches the key passed as the first argument. \index{dbprim_smat@{dbprim\_\-smat}!smat_entry_t@{smat\_\-entry\_\-t}}
 647 \index{smat_entry_t@{smat\_\-entry\_\-t}!dbprim_smat@{dbprim\_\-smat}}
 648 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef struct \_\-smat\_\-entry\_\-s smat\_\-entry\_\-t}\label{group__dbprim__smat_a2}
 649
 650
 651
 652
 653  This structure is allocated by the library and represents a single element in a sparse matrix. \index{dbprim_smat@{dbprim\_\-smat}!smat_head_t@{smat\_\-head\_\-t}}
 654 \index{smat_head_t@{smat\_\-head\_\-t}!dbprim_smat@{dbprim\_\-smat}}
 655 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef struct \_\-smat\_\-head\_\-s smat\_\-head\_\-t}\label{group__dbprim__smat_a1}
 656
 657
 658
 659
 660  This structure is the head of a linked list of sparse matrix entries. \index{dbprim_smat@{dbprim\_\-smat}!smat_iter_t@{smat\_\-iter\_\-t}}
 661 \index{smat_iter_t@{smat\_\-iter\_\-t}!dbprim_smat@{dbprim\_\-smat}}
 662 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef unsigned long($\ast$ smat\_\-iter\_\-t)({\bf smat\_\-table\_\-t} $\ast$, {\bf smat\_\-entry\_\-t} $\ast$, void $\ast$)}\label{group__dbprim__smat_a4}
 663
 664
 665
 666
 667  This function pointer references a callback used by {\bf st\_\-iter}() {\rm (p.\,\pageref{group__dbprim__smat_a13})}, {\bf st\_\-flush}() {\rm (p.\,\pageref{group__dbprim__smat_a14})}, {\bf sh\_\-iter}() {\rm (p.\,\pageref{group__dbprim__smat_a20})}, 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. \index{dbprim_smat@{dbprim\_\-smat}!smat_loc_t@{smat\_\-loc\_\-t}}
 668 \index{smat_loc_t@{smat\_\-loc\_\-t}!dbprim_smat@{dbprim\_\-smat}}
 669 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef enum {\bf \_\-smat\_\-loc\_\-e} smat\_\-loc\_\-t}\label{group__dbprim__smat_a6}
 670
 671
 672
 673
 674  See the documentation for the enumeration {\bf \_\-smat\_\-loc\_\-e} {\rm (p.\,\pageref{group__dbprim__smat_a48})}. \index{dbprim_smat@{dbprim\_\-smat}!smat_resize_t@{smat\_\-resize\_\-t}}
 675 \index{smat_resize_t@{smat\_\-resize\_\-t}!dbprim_smat@{dbprim\_\-smat}}
 676 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef unsigned long($\ast$ smat\_\-resize\_\-t)({\bf smat\_\-table\_\-t} $\ast$, unsigned long)}\label{group__dbprim__smat_a3}
 677
 678
 679
 680
 681  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. \index{dbprim_smat@{dbprim\_\-smat}!smat_table_t@{smat\_\-table\_\-t}}
 682 \index{smat_table_t@{smat\_\-table\_\-t}!dbprim_smat@{dbprim\_\-smat}}
 683 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef struct \_\-smat\_\-table\_\-s smat\_\-table\_\-t}\label{group__dbprim__smat_a0}
 684
 685
 686
 687
 688  This structure is the basis of all sparse matrices maintained by this library.
 689
 690 \subsection{Enumeration Type Documentation}
 691 \index{dbprim_smat@{dbprim\_\-smat}!_smat_loc_e@{\_\-smat\_\-loc\_\-e}}
 692 \index{_smat_loc_e@{\_\-smat\_\-loc\_\-e}!dbprim_smat@{dbprim\_\-smat}}
 693 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}enum \_\-smat\_\-loc\_\-e}\label{group__dbprim__smat_a48}
 694
 695
 696
 697
 698  This enumeration is used to specify whether an element is a row or column element. It should be referenced by the typedef {\bf smat\_\-loc\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a6})}. \begin{Desc}
 699 \item[{\bf Enumeration values:}]\par
 700 \begin{description}
 701 \index{SMAT_LOC_FIRST@{SMAT\_\-LOC\_\-FIRST}!dbprim_smat@{dbprim\_\-smat}}\index{dbprim_smat@{dbprim\_\-smat}!SMAT_LOC_FIRST@{SMAT\_\-LOC\_\-FIRST}}\item[
 702 {\em SMAT\_\-LOC\_\-FIRST}\label{group__dbprim__smat_a48a102}
 703 ]First entry (``row''). \index{SMAT_LOC_SECOND@{SMAT\_\-LOC\_\-SECOND}!dbprim_smat@{dbprim\_\-smat}}\index{dbprim_smat@{dbprim\_\-smat}!SMAT_LOC_SECOND@{SMAT\_\-LOC\_\-SECOND}}\item[
 704 {\em SMAT\_\-LOC\_\-SECOND}\label{group__dbprim__smat_a48a103}
 705 ]Second entry (``column''). \end{description}
 706 \end{Desc}
 707
 708
 709
 710 \subsection{Function Documentation}
 711 \index{dbprim_smat@{dbprim\_\-smat}!sh_find@{sh\_\-find}}
 712 \index{sh_find@{sh\_\-find}!dbprim_smat@{dbprim\_\-smat}}
 713 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long sh\_\-find ({\bf smat\_\-head\_\-t} $\ast$ {\em head}, {\bf smat\_\-entry\_\-t} $\ast$$\ast$ {\em elem\_\-p}, {\bf smat\_\-comp\_\-t} {\em comp\_\-func}, {\bf smat\_\-entry\_\-t} $\ast$ {\em start}, {\bf db\_\-key\_\-t} $\ast$ {\em key})}\label{group__dbprim__smat_a19}
 714
 715
 716
 717
 718  This function iterates through the given row or column of a sparse matrix looking for an element that matches the given {\tt key}.\begin{Desc}
 719 \item[{\bf Parameters: }]\par
 720 \begin{description}
 721 \item[
 722 {\em head}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}. \item[
 723 {\em elem\_\-p}]A pointer to a pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. This is a result pramater. {\tt NULL} is an invalid value. \item[
 724 {\em comp\_\-func}]A pointer to a comparison function used to compare the key to a particular entry. See the documentation for {\bf smat\_\-comp\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a5})} for more information. \item[
 725 {\em start}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} describing where in the row or column to start. If {\tt NULL} is passed, the beginning of the row or column will be assumed. \item[
 726 {\em key}]A key to search for.\end{description}
 727 \end{Desc}
 728 \begin{Desc}
 729 \item[{\bf Return values: }]\par
 730 \begin{description}
 731 \item[
 732 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 733 {\em DB\_\-ERR\_\-WRONGTABLE}]{\tt start} is not in this row or column. \item[
 734 {\em DB\_\-ERR\_\-NOENTRY}]No matching entry was found. \end{description}
 735 \end{Desc}
 736 \index{dbprim_smat@{dbprim\_\-smat}!sh_init@{sh\_\-init}}
 737 \index{sh_init@{sh\_\-init}!dbprim_smat@{dbprim\_\-smat}}
 738 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long sh\_\-init ({\bf smat\_\-head\_\-t} $\ast$ {\em head}, {\bf smat\_\-loc\_\-t} {\em elem}, void $\ast$ {\em object})}\label{group__dbprim__smat_a17}
 739
 740
 741
 742
 743  This function dynamically initializes a sparse matrix row or column linked list head. The {\tt elem} argument specifies whether the object is to be associated with a {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})} list or a {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})} list.\begin{Desc}
 744 \item[{\bf Parameters: }]\par
 745 \begin{description}
 746 \item[
 747 {\em head}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})} to be initialized. \item[
 748 {\em elem}]Either {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})} or {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})}. \item[
 749 {\em object}]A pointer to the object containing the sparse matrix row or column head.\end{description}
 750 \end{Desc}
 751 \begin{Desc}
 752 \item[{\bf Return values: }]\par
 753 \begin{description}
 754 \item[
 755 {\em DB\_\-ERR\_\-BADARGS}]An invalid argument was given. \end{description}
 756 \end{Desc}
 757 \index{dbprim_smat@{dbprim\_\-smat}!sh_iter@{sh\_\-iter}}
 758 \index{sh_iter@{sh\_\-iter}!dbprim_smat@{dbprim\_\-smat}}
 759 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long sh\_\-iter ({\bf smat\_\-head\_\-t} $\ast$ {\em head}, {\bf smat\_\-iter\_\-t} {\em iter\_\-func}, void $\ast$ {\em extra})}\label{group__dbprim__smat_a20}
 760
 761
 762
 763
 764  This function iterates over a row or column of a sparse matrix, executing the given {\tt iter\_\-func} for each entry.\begin{Desc}
 765 \item[{\bf Parameters: }]\par
 766 \begin{description}
 767 \item[
 768 {\em head}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}. \item[
 769 {\em iter\_\-func}]A pointer to a callback function used to perform user-specified actions on an entry in a row or column of a sparse matrix. {\tt NULL} is an invalid value. See the documentation for {\bf smat\_\-iter\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a4})} for more information. \item[
 770 {\em extra}]A {\tt void} pointer that will be passed to {\tt iter\_\-func}.\end{description}
 771 \end{Desc}
 772 \begin{Desc}
 773 \item[{\bf Return values: }]\par
 774 \begin{description}
 775 \item[
 776 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \end{description}
 777 \end{Desc}
 778 \index{dbprim_smat@{dbprim\_\-smat}!sh_move@{sh\_\-move}}
 779 \index{sh_move@{sh\_\-move}!dbprim_smat@{dbprim\_\-smat}}
 780 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long sh\_\-move ({\bf smat\_\-head\_\-t} $\ast$ {\em head}, {\bf smat\_\-entry\_\-t} $\ast$ {\em elem}, {\bf link\_\-loc\_\-t} {\em loc}, {\bf smat\_\-entry\_\-t} $\ast$ {\em elem2})}\label{group__dbprim__smat_a18}
 781
 782
 783
 784
 785  This function allows the specified entry to be shifted within the linked list describing the row or column. It is very similar to the {\bf ll\_\-move}() {\rm (p.\,\pageref{group__dbprim__link_a7})} function.\begin{Desc}
 786 \item[{\bf Parameters: }]\par
 787 \begin{description}
 788 \item[
 789 {\em head}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}. \item[
 790 {\em elem}]A pointer to the {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} describing the entry to be moved. \item[
 791 {\em loc}]A {\bf link\_\-loc\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a4})} indicating where the entry should be moved to. \item[
 792 {\em elem2}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} describing another entry in the list if {\tt loc} is {\bf LINK\_\-LOC\_\-BEFORE} {\rm (p.\,\pageref{group__dbprim__link_a26a100})} or {\bf LINK\_\-LOC\_\-AFTER} {\rm (p.\,\pageref{group__dbprim__link_a26a101})}.\end{description}
 793 \end{Desc}
 794 \begin{Desc}
 795 \item[{\bf Return values: }]\par
 796 \begin{description}
 797 \item[
 798 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 799 {\em DB\_\-ERR\_\-BUSY}]{\tt elem} and {\tt elem2} are the same entry. \item[
 800 {\em DB\_\-ERR\_\-WRONGTABLE}]{\tt elem} or {\tt elem2} are in a different row or column. \item[
 801 {\em DB\_\-ERR\_\-UNUSED}]{\tt elem} or {\tt elem2} are not in any row or column. \end{description}
 802 \end{Desc}
 803 \index{dbprim_smat@{dbprim\_\-smat}!smat_cleanup@{smat\_\-cleanup}}
 804 \index{smat_cleanup@{smat\_\-cleanup}!dbprim_smat@{dbprim\_\-smat}}
 805 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long smat\_\-cleanup (void)}\label{group__dbprim__smat_a7}
 806
 807
 808
 809
 810  This function frees all smat\_\-entry\_\-t objects on the internal free list. It is always successful and returns 0. \index{dbprim_smat@{dbprim\_\-smat}!smat_freemem@{smat\_\-freemem}}
 811 \index{smat_freemem@{smat\_\-freemem}!dbprim_smat@{dbprim\_\-smat}}
 812 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long smat\_\-freemem (void)}\label{group__dbprim__smat_a8}
 813
 814
 815
 816
 817  This function returns the amount of memory being used by the internal free list of smat\_\-entry\_\-t objects.
 818
 819 \begin{Desc}
 820 \item[{\bf Returns: }]\par
 821 A number indicating the size, in bytes, of the memory allocated for smat\_\-entry\_\-t objects on the free list. \end{Desc}
 822 \index{dbprim_smat@{dbprim\_\-smat}!st_add@{st\_\-add}}
 823 \index{st_add@{st\_\-add}!dbprim_smat@{dbprim\_\-smat}}
 824 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long st\_\-add ({\bf smat\_\-table\_\-t} $\ast$ {\em table}, {\bf smat\_\-entry\_\-t} $\ast$$\ast$ {\em entry\_\-p}, {\bf smat\_\-head\_\-t} $\ast$ {\em head1}, {\bf link\_\-loc\_\-t} {\em loc1}, {\bf smat\_\-entry\_\-t} $\ast$ {\em ent1}, {\bf smat\_\-head\_\-t} $\ast$ {\em head2}, {\bf link\_\-loc\_\-t} {\em loc2}, {\bf smat\_\-entry\_\-t} $\ast$ {\em ent2})}\label{group__dbprim__smat_a10}
 825
 826
 827
 828
 829  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 {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} and return it through the {\tt entry\_\-p} result parameter.\begin{Desc}
 830 \item[{\bf Parameters: }]\par
 831 \begin{description}
 832 \item[
 833 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}. \item[
 834 {\em entry\_\-p}]A pointer to a pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. This is a result parameter. If {\tt NULL} is passed, the addition will be performed and an appropriate error code returned. \item[
 835 {\em head1}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})} representing a {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})} sparse matrix list. \item[
 836 {\em loc1}]A {\bf link\_\-loc\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a4})} indicating where the entry should be added for {\tt head1}. \item[
 837 {\em ent1}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} describing another element in the list represented by {\tt head1} if {\tt loc1} is {\bf LINK\_\-LOC\_\-BEFORE} {\rm (p.\,\pageref{group__dbprim__link_a26a100})} or {\bf LINK\_\-LOC\_\-AFTER} {\rm (p.\,\pageref{group__dbprim__link_a26a101})}. \item[
 838 {\em head2}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})} representing a {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})} sparse matrix list. \item[
 839 {\em loc2}]A {\bf link\_\-loc\_\-t} {\rm (p.\,\pageref{group__dbprim__link_a4})} indicating where the entry should be added for {\tt head2}. \item[
 840 {\em ent2}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} describing another element in the list represented by {\tt head2} if {\tt loc2} is {\bf LINK\_\-LOC\_\-BEFORE} {\rm (p.\,\pageref{group__dbprim__link_a26a100})} or {\bf LINK\_\-LOC\_\-AFTER} {\rm (p.\,\pageref{group__dbprim__link_a26a101})}.\end{description}
 841 \end{Desc}
 842 \begin{Desc}
 843 \item[{\bf Return values: }]\par
 844 \begin{description}
 845 \item[
 846 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 847 {\em DB\_\-ERR\_\-BUSY}]One of the arguments is already in the table. \item[
 848 {\em DB\_\-ERR\_\-FROZEN}]The table is currently frozen. \item[
 849 {\em DB\_\-ERR\_\-NOTABLE}]The bucket table has not been allocated and automatic growth is not enabled. \item[
 850 {\em DB\_\-ERR\_\-WRONGTABLE}]One of the arguments was not in the proper table or list. \item[
 851 {\em DB\_\-ERR\_\-UNUSED}]One of the {\tt ent} arguments is not presently in a list. \item[
 852 {\em DB\_\-ERR\_\-UNRECOVERABLE}]An unrecoverable error occurred while resizing the table. \item[
 853 {\em ENOMEM}]No memory could be allocated for the {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} structure. \end{description}
 854 \end{Desc}
 855 \index{dbprim_smat@{dbprim\_\-smat}!st_find@{st\_\-find}}
 856 \index{st_find@{st\_\-find}!dbprim_smat@{dbprim\_\-smat}}
 857 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long st\_\-find ({\bf smat\_\-table\_\-t} $\ast$ {\em table}, {\bf smat\_\-entry\_\-t} $\ast$$\ast$ {\em entry\_\-p}, {\bf smat\_\-head\_\-t} $\ast$ {\em head1}, {\bf smat\_\-head\_\-t} $\ast$ {\em head2})}\label{group__dbprim__smat_a12}
 858
 859
 860
 861
 862  This function looks up the entry matching the given {\tt head1} and {\tt head2}.\begin{Desc}
 863 \item[{\bf Parameters: }]\par
 864 \begin{description}
 865 \item[
 866 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}. \item[
 867 {\em entry\_\-p}]A pointer to a pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}. This is a result parameter. If {\tt NULL} is passed, the lookup will be performed and an appropriate error code returned. \item[
 868 {\em head1}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})} initialized to {\bf SMAT\_\-LOC\_\-FIRST} {\rm (p.\,\pageref{group__dbprim__smat_a48a102})}. \item[
 869 {\em head2}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})} initialized to {\bf SMAT\_\-LOC\_\-SECOND} {\rm (p.\,\pageref{group__dbprim__smat_a48a103})}.\end{description}
 870 \end{Desc}
 871 \begin{Desc}
 872 \item[{\bf Return values: }]\par
 873 \begin{description}
 874 \item[
 875 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 876 {\em DB\_\-ERR\_\-WRONGTABLE}]One or both of {\tt head1} or {\tt head2} are not referenced in this table. \item[
 877 {\em DB\_\-ERR\_\-NOENTRY}]No matching entry was found. \end{description}
 878 \end{Desc}
 879 \index{dbprim_smat@{dbprim\_\-smat}!st_flush@{st\_\-flush}}
 880 \index{st_flush@{st\_\-flush}!dbprim_smat@{dbprim\_\-smat}}
 881 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long st\_\-flush ({\bf smat\_\-table\_\-t} $\ast$ {\em table}, {\bf smat\_\-iter\_\-t} {\em flush\_\-func}, void $\ast$ {\em extra})}\label{group__dbprim__smat_a14}
 882
 883
 884
 885
 886  This function flushes a sparse matrix--that is, it removes each entry from the matrix. If a {\tt flush\_\-func} is specified, it will be called on the entry after it has been removed from the table, and may safely call {\tt free()}.\begin{Desc}
 887 \item[{\bf Parameters: }]\par
 888 \begin{description}
 889 \item[
 890 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}. \item[
 891 {\em flush\_\-func}]A pointer to a callback function used to perform user-specified actions on an entry after removing it from the table. May be {\tt NULL}. See the documentation for {\bf smat\_\-iter\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a4})} for more information. \item[
 892 {\em extra}]A {\tt void} pointer that will be passed to {\tt iter\_\-func}.\end{description}
 893 \end{Desc}
 894 \begin{Desc}
 895 \item[{\bf Return values: }]\par
 896 \begin{description}
 897 \item[
 898 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 899 {\em DB\_\-ERR\_\-FROZEN}]The sparse matrix is frozen. \end{description}
 900 \end{Desc}
 901 \index{dbprim_smat@{dbprim\_\-smat}!st_free@{st\_\-free}}
 902 \index{st_free@{st\_\-free}!dbprim_smat@{dbprim\_\-smat}}
 903 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long st\_\-free ({\bf smat\_\-table\_\-t} $\ast$ {\em table})}\label{group__dbprim__smat_a16}
 904
 905
 906
 907
 908  This function releases the memory used by the bucket table of the empty hash table associated with a sparse matrix.\begin{Desc}
 909 \item[{\bf Parameters: }]\par
 910 \begin{description}
 911 \item[
 912 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.\end{description}
 913 \end{Desc}
 914 \begin{Desc}
 915 \item[{\bf Return values: }]\par
 916 \begin{description}
 917 \item[
 918 {\em DB\_\-ERR\_\-BADARGS}]An invalid argument was given. \item[
 919 {\em DB\_\-ERR\_\-FROZEN}]The table is frozen. \item[
 920 {\em DB\_\-ERR\_\-NOTEMPTY}]The table is not empty. \end{description}
 921 \end{Desc}
 922 \index{dbprim_smat@{dbprim\_\-smat}!st_init@{st\_\-init}}
 923 \index{st_init@{st\_\-init}!dbprim_smat@{dbprim\_\-smat}}
 924 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long st\_\-init ({\bf smat\_\-table\_\-t} $\ast$ {\em table}, unsigned long {\em flags}, {\bf smat\_\-resize\_\-t} {\em resize}, void $\ast$ {\em extra}, unsigned long {\em init\_\-mod})}\label{group__dbprim__smat_a9}
 925
 926
 927 This function dynamically initializes a sparse matrix table.\begin{Desc}
 928 \item[{\bf Parameters: }]\par
 929 \begin{description}
 930 \item[
 931 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})} to be initialized. \item[
 932 {\em flags}]A bit-wise OR of {\bf HASH\_\-FLAG\_\-AUTOGROW} {\rm (p.\,\pageref{group__dbprim__hash_a16})} and {\bf HASH\_\-FLAG\_\-AUTOSHRINK} {\rm (p.\,\pageref{group__dbprim__hash_a17})}. If neither behavior is desired, use 0. \item[
 933 {\em resize}]A {\bf hash\_\-resize\_\-t} {\rm (p.\,\pageref{group__dbprim__hash_a5})} function pointer for determining whether resizing is permitted and/or for notification of the resize. \item[
 934 {\em extra}]Extra pointer data that should be associated with the sparse matrix table. \item[
 935 {\em init\_\-mod}]An initial modulus for the table. This will presumably be extracted by {\bf st\_\-modulus}() {\rm (p.\,\pageref{group__dbprim__smat_a25})} in a previous invocation of the application. A 0 value is valid.\end{description}
 936 \end{Desc}
 937 \begin{Desc}
 938 \item[{\bf Return values: }]\par
 939 \begin{description}
 940 \item[
 941 {\em DB\_\-ERR\_\-BADARGS}]An invalid argument was given. \item[
 942 {\em ENOMEM}]Unable to allocate memory. \end{description}
 943 \end{Desc}
 944 \index{dbprim_smat@{dbprim\_\-smat}!st_iter@{st\_\-iter}}
 945 \index{st_iter@{st\_\-iter}!dbprim_smat@{dbprim\_\-smat}}
 946 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long st\_\-iter ({\bf smat\_\-table\_\-t} $\ast$ {\em table}, {\bf smat\_\-iter\_\-t} {\em iter\_\-func}, void $\ast$ {\em extra})}\label{group__dbprim__smat_a13}
 947
 948
 949
 950
 951  This function iterates over every entry in a sparse matrix (in an unspecified order), executing the given {\tt iter\_\-func} on each entry.\begin{Desc}
 952 \item[{\bf Parameters: }]\par
 953 \begin{description}
 954 \item[
 955 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}. \item[
 956 {\em iter\_\-func}]A pointer to a callback function used to perform user-specified actions on an entry in a sparse matrix. {\tt NULL} is an invalid value. See the documentation for {\bf smat\_\-iter\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a4})} for more information. \item[
 957 {\em extra}]A {\tt void} pointer that will be passed to {\tt iter\_\-func}.\end{description}
 958 \end{Desc}
 959 \begin{Desc}
 960 \item[{\bf Return values: }]\par
 961 \begin{description}
 962 \item[
 963 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
 964 {\em DB\_\-ERR\_\-FROZEN}]The sparse matrix is frozen. \end{description}
 965 \end{Desc}
 966 \index{dbprim_smat@{dbprim\_\-smat}!st_remove@{st\_\-remove}}
 967 \index{st_remove@{st\_\-remove}!dbprim_smat@{dbprim\_\-smat}}
 968 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long st\_\-remove ({\bf smat\_\-table\_\-t} $\ast$ {\em table}, {\bf smat\_\-entry\_\-t} $\ast$ {\em entry})}\label{group__dbprim__smat_a11}
 969
 970
 971
 972
 973  This function removes the given entry from the specified sparse matrix.\begin{Desc}
 974 \item[{\bf Parameters: }]\par
 975 \begin{description}
 976 \item[
 977 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}. \item[
 978 {\em entry}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})} to be removed from the table.\end{description}
 979 \end{Desc}
 980 \begin{Desc}
 981 \item[{\bf Return values: }]\par
 982 \begin{description}
 983 \item[
 984 {\em DB\_\-ERR\_\-BADARGS}]An invalid argument was given. \item[
 985 {\em DB\_\-ERR\_\-WRONGTABLE}]Entry is not in this sparse matrix. \item[
 986 {\em DB\_\-ERR\_\-UNRECOVERABLE}]An unrecoverable error occurred while removing the entry from the table. \end{description}
 987 \end{Desc}
 988 \index{dbprim_smat@{dbprim\_\-smat}!st_resize@{st\_\-resize}}
 989 \index{st_resize@{st\_\-resize}!dbprim_smat@{dbprim\_\-smat}}
 990 \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned long st\_\-resize ({\bf smat\_\-table\_\-t} $\ast$ {\em table}, unsigned long {\em new\_\-size})}\label{group__dbprim__smat_a15}
 991
 992
 993
 994
 995  This function resizes the hash table associated with a sparse matrix based on the {\tt new\_\-size} parameter. See the documentation for {\bf ht\_\-resize}() {\rm (p.\,\pageref{group__dbprim__hash_a13})} for more information.\begin{Desc}
 996 \item[{\bf Parameters: }]\par
 997 \begin{description}
 998 \item[
 999 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}. \item[
1000 {\em new\_\-size}]A new size value for the table.\end{description}
1001 \end{Desc}
1002 \begin{Desc}
1003 \item[{\bf Return values: }]\par
1004 \begin{description}
1005 \item[
1006 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
1007 {\em DB\_\-ERR\_\-FROZEN}]The table is currently frozen. \item[
1008 {\em DB\_\-ERR\_\-UNRECOVERABLE}]A catastrophic error was encountered. The table is now unusable. \item[
1009 {\em ENOMEM}]No memory could be allocated for the new bucket table. \end{description}
1010 \end{Desc}