1 \section{Sparse matrices}
2 \label{group__dbprim__smat}\index{Sparse matrices@{Sparse matrices}}
3 Operations for sparse matrices.
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}
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}
81 enum {\bf \_\-smat\_\-loc\_\-e} \{ {\bf SMAT\_\-LOC\_\-FIRST},
82 {\bf SMAT\_\-LOC\_\-SECOND}
84 \begin{CompactList}\small\item\em Sparse matrix location.\item\end{CompactList}\end{CompactItemize}
85 \subsection*{Functions}
86 \begin{CompactItemize}
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)
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}
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.
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.
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.
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.
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.)
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})}.
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.
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}
141 This macro statically initializes a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.\begin{Desc}
142 \item[{\bf Parameters: }]\par
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}
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}
155 This macro statically initializes a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.\begin{Desc}
156 \item[{\bf Parameters: }]\par
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}
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}
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}
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
181 {\em entry}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}.
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}
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
199 {\em entry}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}.
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}
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
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.
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}
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.
235 \item[{\bf Warning: }]\par
236 This macro may evaluate the {\tt entry} and {\tt n} arguments twice.\end{Desc}
238 \item[{\bf Parameters: }]\par
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.
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}
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
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.
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}
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.
278 \item[{\bf Warning: }]\par
279 This macro may evaluate the {\tt entry} and {\tt n} arguments twice.\end{Desc}
281 \item[{\bf Parameters: }]\par
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.
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}
299 This macro retrieves a pointer to the table that the sparse matrix entry is in.\begin{Desc}
300 \item[{\bf Parameters: }]\par
303 {\em entry}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}.
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}
317 This macro verifies that a given pointer actually does point to a sparse matrix entry.\begin{Desc}
318 \item[{\bf Parameters: }]\par
321 {\em entry}]A pointer to a {\bf smat\_\-entry\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a2})}.
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}
335 This macro retrieves the number of elements in the sparse matrix list rooted at {\tt head}.\begin{Desc}
336 \item[{\bf Parameters: }]\par
339 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
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}
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
357 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
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}
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.
374 \item[{\bf Warning: }]\par
375 This macro may evaluate the {\tt head} argument twice.\end{Desc}
377 \item[{\bf Parameters: }]\par
380 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
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}
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
398 {\em head}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
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}
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.
415 \item[{\bf Warning: }]\par
416 This macro may evaluate the {\tt head} argument twice.\end{Desc}
418 \item[{\bf Parameters: }]\par
421 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
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}
435 This macro retrieves a pointer to the object referenced by the sparse matrix list head.\begin{Desc}
436 \item[{\bf Parameters: }]\par
439 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
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}
453 This macro returns the physical size of the memory allocated by the library for this sparse matrix list.
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}
459 \item[{\bf Parameters: }]\par
462 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
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}
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
480 {\em head}]A pointer to {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
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}
494 This macro verifies that a given pointer actually does point to a sparse matrix head.\begin{Desc}
495 \item[{\bf Parameters: }]\par
498 {\em head}]A pointer to a {\bf smat\_\-head\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a1})}.
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}
512 This macro retrieves the total number of items actually in the sparse matrix table.\begin{Desc}
513 \item[{\bf Parameters: }]\par
516 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
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}
530 This macro retrieves the extra pointer data associated with a particular sparse matrix table.\begin{Desc}
531 \item[{\bf Parameters: }]\par
534 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
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}
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
552 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
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}
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
570 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
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}
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
588 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
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}
602 This macro returns the physical size of the memory allocated by the library for this sparse matrix table.
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}
608 \item[{\bf Parameters: }]\par
611 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
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}
625 This macro verifies that a given pointer actually does point to a sparse matrix table.\begin{Desc}
626 \item[{\bf Parameters: }]\par
629 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.
634 \item[{\bf Returns: }]\par
635 Boolean true if {\tt table} is a valid sparse matrix table or false otherwise. \end{Desc}
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}
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}
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}
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}
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}
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}
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}
688 This structure is the basis of all sparse matrices maintained by this library.
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}
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
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}
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}
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
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}
729 \item[{\bf Return values: }]\par
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}
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}
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
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}
752 \item[{\bf Return values: }]\par
755 {\em DB\_\-ERR\_\-BADARGS}]An invalid argument was given. \end{description}
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}
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
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}
773 \item[{\bf Return values: }]\par
776 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \end{description}
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}
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
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}
795 \item[{\bf Return values: }]\par
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}
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}
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}
817 This function returns the amount of memory being used by the internal free list of smat\_\-entry\_\-t objects.
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}
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
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}
843 \item[{\bf Return values: }]\par
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}
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}
862 This function looks up the entry matching the given {\tt head1} and {\tt head2}.\begin{Desc}
863 \item[{\bf Parameters: }]\par
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}
872 \item[{\bf Return values: }]\par
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}
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}
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
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}
895 \item[{\bf Return values: }]\par
898 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
899 {\em DB\_\-ERR\_\-FROZEN}]The sparse matrix is frozen. \end{description}
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}
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
912 {\em table}]A pointer to a {\bf smat\_\-table\_\-t} {\rm (p.\,\pageref{group__dbprim__smat_a0})}.\end{description}
915 \item[{\bf Return values: }]\par
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}
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}
927 This function dynamically initializes a sparse matrix table.\begin{Desc}
928 \item[{\bf Parameters: }]\par
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}
938 \item[{\bf Return values: }]\par
941 {\em DB\_\-ERR\_\-BADARGS}]An invalid argument was given. \item[
942 {\em ENOMEM}]Unable to allocate memory. \end{description}
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}
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
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}
960 \item[{\bf Return values: }]\par
963 {\em DB\_\-ERR\_\-BADARGS}]An argument was invalid. \item[
964 {\em DB\_\-ERR\_\-FROZEN}]The sparse matrix is frozen. \end{description}
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}
973 This function removes the given entry from the specified sparse matrix.\begin{Desc}
974 \item[{\bf Parameters: }]\par
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}
981 \item[{\bf Return values: }]\par
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}
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}
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
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}
1003 \item[{\bf Return values: }]\par
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}