libs/dbprim/doc/man/man3/dbprim_smat.3

   1 .TH "Sparse matrices" 3 "6 Mar 2003" "dbprim" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 Sparse matrices \- Operations for sparse matrices.
   6 More...
   7 .SS "Defines"
   8
   9 .in +1c
  10 .ti -1c
  11 .RI "#define \fBSMAT_TABLE_INIT\fP(flags, resize, extra)"
  12 .br
  13 .RI "\fISparse matrix table static initializer.\fP"
  14 .ti -1c
  15 .RI "#define \fBst_verify\fP(table)"
  16 .br
  17 .RI "\fISparse matrix table verification macro.\fP"
  18 .ti -1c
  19 .RI "#define \fBst_flags\fP(table)"
  20 .br
  21 .RI "\fISparse matrix table flags.\fP"
  22 .ti -1c
  23 .RI "#define \fBst_frozen\fP(table)"
  24 .br
  25 .RI "\fIDetermine if a sparse matrix is frozen.\fP"
  26 .ti -1c
  27 .RI "#define \fBst_modulus\fP(table)"
  28 .br
  29 .RI "\fISparse matrix table modulus.\fP"
  30 .ti -1c
  31 .RI "#define \fBst_count\fP(table)"
  32 .br
  33 .RI "\fISparse matrix table count.\fP"
  34 .ti -1c
  35 .RI "#define \fBst_extra\fP(table)"
  36 .br
  37 .RI "\fIExtra pointer data in a sparse matrix table.\fP"
  38 .ti -1c
  39 .RI "#define \fBst_size\fP(table)"
  40 .br
  41 .RI "\fISparse matrix table memory size.\fP"
  42 .ti -1c
  43 .RI "#define \fBSMAT_HEAD_INIT\fP(elem, object)"
  44 .br
  45 .RI "\fISparse matrix list head static initializer.\fP"
  46 .ti -1c
  47 .RI "#define \fBsh_verify\fP(head)"
  48 .br
  49 .RI "\fISparse matrix list head verification macro.\fP"
  50 .ti -1c
  51 .RI "#define \fBsh_elem\fP(head)"
  52 .br
  53 .RI "\fISparse matrix list head element macro.\fP"
  54 .ti -1c
  55 .RI "#define \fBsh_table\fP(head)"
  56 .br
  57 .RI "\fISparse matrix list head table pointer.\fP"
  58 .ti -1c
  59 .RI "#define \fBsh_frozen\fP(head)"
  60 .br
  61 .RI "\fIDetermine if a sparse matrix is frozen.\fP"
  62 .ti -1c
  63 .RI "#define \fBsh_count\fP(head)"
  64 .br
  65 .RI "\fISparse matrix list count.\fP"
  66 .ti -1c
  67 .RI "#define \fBsh_first\fP(head)"
  68 .br
  69 .RI "\fIFirst element in sparse matrix list.\fP"
  70 .ti -1c
  71 .RI "#define \fBsh_last\fP(head)"
  72 .br
  73 .RI "\fILast element in sparse matrix list.\fP"
  74 .ti -1c
  75 .RI "#define \fBsh_object\fP(head)"
  76 .br
  77 .RI "\fIObject represented by a sparse matrix list head.\fP"
  78 .ti -1c
  79 .RI "#define \fBsh_size\fP(head)"
  80 .br
  81 .RI "\fISparse matrix list memory size.\fP"
  82 .ti -1c
  83 .RI "#define \fBse_verify\fP(entry)"
  84 .br
  85 .RI "\fISparse matrix entry verification macro.\fP"
  86 .ti -1c
  87 .RI "#define \fBse_table\fP(entry)"
  88 .br
  89 .RI "\fISparse matrix entry table.\fP"
  90 .ti -1c
  91 .RI "#define \fB_se_link\fP(entry)"
  92 .br
  93 .RI "\fISparse matrix entry linked list element.\fP"
  94 .ti -1c
  95 .RI "#define \fBse_flags\fP(entry)"
  96 .br
  97 .RI "\fISparse matrix entry flags.\fP"
  98 .ti -1c
  99 .RI "#define \fBse_hash\fP(entry)"
 100 .br
 101 .RI "\fISparse matrix table entry hash value.\fP"
 102 .ti -1c
 103 .RI "#define \fBse_next\fP(entry, n)"
 104 .br
 105 .RI "\fINext element in sparse matrix list.\fP"
 106 .ti -1c
 107 .RI "#define \fBse_prev\fP(entry, n)"
 108 .br
 109 .RI "\fIPrevious element in sparse matrix list.\fP"
 110 .ti -1c
 111 .RI "#define \fBse_lflags\fP(entry, n)"
 112 .br
 113 .RI "\fIFlags associated with an entry in a sparse matrix list.\fP"
 114 .ti -1c
 115 .RI "#define \fBse_object\fP(entry, n)"
 116 .br
 117 .RI "\fIObject associated with an entry in a sparse matrix list.\fP"
 118 .in -1c
 119 .SS "Typedefs"
 120
 121 .in +1c
 122 .ti -1c
 123 .RI "typedef struct _smat_table_s \fBsmat_table_t\fP"
 124 .br
 125 .RI "\fISparse matrix table.\fP"
 126 .ti -1c
 127 .RI "typedef struct _smat_head_s \fBsmat_head_t\fP"
 128 .br
 129 .RI "\fISparse matrix list head.\fP"
 130 .ti -1c
 131 .RI "typedef struct _smat_entry_s \fBsmat_entry_t\fP"
 132 .br
 133 .RI "\fISparse matrix entry.\fP"
 134 .ti -1c
 135 .RI "typedef unsigned long (* \fBsmat_resize_t\fP )(\fBsmat_table_t\fP *, unsigned long)"
 136 .br
 137 .RI "\fISparse matrix table resize callback.\fP"
 138 .ti -1c
 139 .RI "typedef unsigned long (* \fBsmat_iter_t\fP )(\fBsmat_table_t\fP *, \fBsmat_entry_t\fP *, void *)"
 140 .br
 141 .RI "\fISparse matrix iteration callback.\fP"
 142 .ti -1c
 143 .RI "typedef unsigned long (* \fBsmat_comp_t\fP )(\fBdb_key_t\fP *, \fBsmat_entry_t\fP *)"
 144 .br
 145 .RI "\fISparse matrix comparison callback.\fP"
 146 .ti -1c
 147 .RI "typedef enum \fB_smat_loc_e\fP \fBsmat_loc_t\fP"
 148 .br
 149 .RI "\fISparse matrix location.\fP"
 150 .in -1c
 151 .SS "Enumerations"
 152
 153 .in +1c
 154 .ti -1c
 155 .RI "enum \fB_smat_loc_e\fP { \fBSMAT_LOC_FIRST\fP, \fBSMAT_LOC_SECOND\fP }"
 156 .br
 157 .RI "\fISparse matrix location.\fP"
 158 .in -1c
 159 .SS "Functions"
 160
 161 .in +1c
 162 .ti -1c
 163 .RI "unsigned long \fBsmat_cleanup\fP (void)"
 164 .br
 165 .RI "\fIClean up the smat free list.\fP"
 166 .ti -1c
 167 .RI "unsigned long \fBsmat_freemem\fP (void)"
 168 .br
 169 .RI "\fIReport how much memory is used by the free list.\fP"
 170 .ti -1c
 171 .RI "unsigned long \fBst_init\fP (\fBsmat_table_t\fP *table, unsigned long flags, \fBsmat_resize_t\fP resize, void *extra, unsigned long init_mod)"
 172 .br
 173 .ti -1c
 174 .RI "unsigned long \fBst_add\fP (\fBsmat_table_t\fP *table, \fBsmat_entry_t\fP **entry_p, \fBsmat_head_t\fP *head1, \fBlink_loc_t\fP loc1, \fBsmat_entry_t\fP *ent1, \fBsmat_head_t\fP *head2, \fBlink_loc_t\fP loc2, \fBsmat_entry_t\fP *ent2)"
 175 .br
 176 .RI "\fIAdd an entry to a sparse matrix.\fP"
 177 .ti -1c
 178 .RI "unsigned long \fBst_remove\fP (\fBsmat_table_t\fP *table, \fBsmat_entry_t\fP *entry)"
 179 .br
 180 .RI "\fIRemove an entry from a sparse matrix.\fP"
 181 .ti -1c
 182 .RI "unsigned long \fBst_find\fP (\fBsmat_table_t\fP *table, \fBsmat_entry_t\fP **entry_p, \fBsmat_head_t\fP *head1, \fBsmat_head_t\fP *head2)"
 183 .br
 184 .RI "\fIFind an entry in a sparse matrix.\fP"
 185 .ti -1c
 186 .RI "unsigned long \fBst_iter\fP (\fBsmat_table_t\fP *table, \fBsmat_iter_t\fP iter_func, void *extra)"
 187 .br
 188 .RI "\fIIterate over each entry in a sparse matrix.\fP"
 189 .ti -1c
 190 .RI "unsigned long \fBst_flush\fP (\fBsmat_table_t\fP *table, \fBsmat_iter_t\fP flush_func, void *extra)"
 191 .br
 192 .RI "\fIFlush a sparse matrix.\fP"
 193 .ti -1c
 194 .RI "unsigned long \fBst_resize\fP (\fBsmat_table_t\fP *table, unsigned long new_size)"
 195 .br
 196 .RI "\fIResize a sparse matrix table.\fP"
 197 .ti -1c
 198 .RI "unsigned long \fBst_free\fP (\fBsmat_table_t\fP *table)"
 199 .br
 200 .RI "\fIFree memory used by an empty sparse matrix table.\fP"
 201 .ti -1c
 202 .RI "unsigned long \fBsh_init\fP (\fBsmat_head_t\fP *head, \fBsmat_loc_t\fP elem, void *object)"
 203 .br
 204 .RI "\fIDynamically initialize a sparse matrix row or column head.\fP"
 205 .ti -1c
 206 .RI "unsigned long \fBsh_move\fP (\fBsmat_head_t\fP *head, \fBsmat_entry_t\fP *elem, \fBlink_loc_t\fP loc, \fBsmat_entry_t\fP *elem2)"
 207 .br
 208 .RI "\fIMove an entry within a row or column list.\fP"
 209 .ti -1c
 210 .RI "unsigned long \fBsh_find\fP (\fBsmat_head_t\fP *head, \fBsmat_entry_t\fP **elem_p, \fBsmat_comp_t\fP comp_func, \fBsmat_entry_t\fP *start, \fBdb_key_t\fP *key)"
 211 .br
 212 .RI "\fIFind an entry in a row or column of a sparse matrix.\fP"
 213 .ti -1c
 214 .RI "unsigned long \fBsh_iter\fP (\fBsmat_head_t\fP *head, \fBsmat_iter_t\fP iter_func, void *extra)"
 215 .br
 216 .RI "\fIIterate over each entry in a row or column of a sparse matrix.\fP"
 217 .in -1c
 218 .SH "DETAILED DESCRIPTION"
 219 .PP
 220 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.
 221 .PP
 222 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.
 223 .PP
 224 Because sparse matrices are so complicated, there are three structures and a variety of operations used. Two of the structures, \fBsmat_table_t\fP and \fBsmat_head_t\fP, are caller-allocated. However, the third structure, \fBsmat_entry_t\fP, 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 \fBsmat_cleanup\fP() and \fBsmat_freemem\fP() calls.
 225 .PP
 226 The \fBsmat_table_t\fP contains the hash table. Only one of these need be allocated per type of association--for instance, in the above example, only one \fBsmat_table_t\fP needs to be allocated to represent the manager-employee relationship.
 227 .PP
 228 The \fBsmat_head_t\fP contains the linked list. There are actually two kinds of these structures--one is \fBSMAT_LOC_FIRST\fP, which could be regarded as a ``row,'' and the other is \fBSMAT_LOC_SECOND\fP, 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 \fBsmat_head_t\fP for a manager may be \fBSMAT_LOC_FIRST\fP, and one for an employee must then be \fBSMAT_LOC_SECOND\fP. (These values are set when initializing the \fBsmat_head_t\fP structure.)
 229 .PP
 230 An association may be created with the \fBst_add\fP() 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 \fBst_remove\fP(), or looked up with \fBst_find\fP(). If iteration over all associations is desired, use the \fBst_iter\fP() function. Removing all associations from a table may be performed with \fBst_flush\fP(), which optionally calls a user-defined clean-up function. The associated hash table may be resized with \fBst_resize\fP(), and the bucket table may be released with \fBst_free\fP().
 231 .PP
 232 An association may also be reordered within the linked lists using the \fBsh_move\fP() function. If a particular entry is desired, use the \fBsh_find\fP() function with a user-defined comparison function to locate it. Iteration may be performed with the \fBsh_iter\fP() 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.
 233 .SH "DEFINE DOCUMENTATION"
 234 .PP
 235 .SS "#define SMAT_HEAD_INIT(elem, object)"
 236 .PP
 237 .PP
 238  This macro statically initializes a \fBsmat_head_t\fP.
 239 .PP
 240 \fBParameters: \fP
 241 .in +1c
 242 .TP
 243 \fB\fIelem\fP\fP
 244 One of \fBSMAT_LOC_FIRST\fP or \fBSMAT_LOC_SECOND\fP specifing whether the object is a member of the set of rows or columns.
 245 .TP
 246 \fB\fIobject\fP\fP
 247 A pointer to \fCvoid\fP representing the object associated with the list head.
 248 .SS "#define SMAT_TABLE_INIT(flags, resize, extra)"
 249 .PP
 250 .PP
 251  This macro statically initializes a \fBsmat_table_t\fP.
 252 .PP
 253 \fBParameters: \fP
 254 .in +1c
 255 .TP
 256 \fB\fIflags\fP\fP
 257 A bit-wise OR of \fBHASH_FLAG_AUTOGROW\fP and \fBHASH_FLAG_AUTOSHRINK\fP. If neither behavior is desired, use 0.
 258 .TP
 259 \fB\fIresize\fP\fP
 260 A \fBsmat_resize_t\fP function pointer for determining whether resizing is permitted and/or for notification of the resize.
 261 .TP
 262 \fB\fIextra\fP\fP
 263 Extra pointer data that should be associated with the sparse matrix.
 264 .SS "#define _se_link(entry)"
 265 .PP
 266 .PP
 267 For internal use only.
 268 .SS "#define se_flags(entry)"
 269 .PP
 270 .PP
 271  This macro retrieves a set of user-defined flags associated with the entry. It may be used as an lvalue to set those flags.
 272 .PP
 273 \fBParameters: \fP
 274 .in +1c
 275 .TP
 276 \fB\fIentry\fP\fP
 277 A pointer to a \fBsmat_entry_t\fP.
 278 .PP
 279 \fBReturns: \fP
 280 .in +1c
 281 An \fCunsigned long\fP containing the flags associated with the entry.
 282 .SS "#define se_hash(entry)"
 283 .PP
 284 .PP
 285  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.
 286 .PP
 287 \fBParameters: \fP
 288 .in +1c
 289 .TP
 290 \fB\fIentry\fP\fP
 291 A pointer to a \fBsmat_entry_t\fP.
 292 .PP
 293 \fBReturns: \fP
 294 .in +1c
 295 An \fCunsigned long\fP containing the hash code for the entry.
 296 .SS "#define se_lflags(entry, n)"
 297 .PP
 298 .PP
 299  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.
 300 .PP
 301 \fBParameters: \fP
 302 .in +1c
 303 .TP
 304 \fB\fIentry\fP\fP
 305 A pointer to \fBsmat_entry_t\fP.
 306 .TP
 307 \fB\fIn\fP\fP
 308 One of \fBSMAT_LOC_FIRST\fP or \fBSMAT_LOC_SECOND\fP to specify which list thread is desired.
 309 .PP
 310 \fBReturns: \fP
 311 .in +1c
 312 An \fCunsigned long\fP containing the flags associated with the entry.
 313 .SS "#define se_next(entry, n)"
 314 .PP
 315 .PP
 316  This macro retrieves a pointer to the \fBlink_elem_t\fP for the next element in the sparse matrix list.
 317 .PP
 318 \fBWarning: \fP
 319 .in +1c
 320 This macro may evaluate the \fCentry\fP and \fCn\fP arguments twice.
 321 .PP
 322 \fBParameters: \fP
 323 .in +1c
 324 .TP
 325 \fB\fIentry\fP\fP
 326 A pointer to \fBsmat_entry_t\fP.
 327 .TP
 328 \fB\fIn\fP\fP
 329 One of \fBSMAT_LOC_FIRST\fP or \fBSMAT_LOC_SECOND\fP to specify which list thread is desired.
 330 .PP
 331 \fBReturns: \fP
 332 .in +1c
 333 A pointer to \fBsmat_entry_t\fP.
 334 .SS "#define se_object(entry, n)"
 335 .PP
 336 .PP
 337  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.
 338 .PP
 339 \fBParameters: \fP
 340 .in +1c
 341 .TP
 342 \fB\fIentry\fP\fP
 343 A pointer to \fBsmat_entry_t\fP.
 344 .TP
 345 \fB\fIn\fP\fP
 346 One of \fBSMAT_LOC_FIRST\fP or \fBSMAT_LOC_SECOND\fP to specify which list thread is desired.
 347 .PP
 348 \fBReturns: \fP
 349 .in +1c
 350 A pointer to \fCvoid\fP representing the object.
 351 .SS "#define se_prev(entry, n)"
 352 .PP
 353 .PP
 354  This macro retrieves a pointer to the \fBlink_elem_t\fP for the previous element in the sparse matrix list.
 355 .PP
 356 \fBWarning: \fP
 357 .in +1c
 358 This macro may evaluate the \fCentry\fP and \fCn\fP arguments twice.
 359 .PP
 360 \fBParameters: \fP
 361 .in +1c
 362 .TP
 363 \fB\fIentry\fP\fP
 364 A pointer to \fBsmat_entry_t\fP.
 365 .TP
 366 \fB\fIn\fP\fP
 367 One of \fBSMAT_LOC_FIRST\fP or \fBSMAT_LOC_SECOND\fP to specify which list thread is desired.
 368 .PP
 369 \fBReturns: \fP
 370 .in +1c
 371 A pointer to \fBsmat_entry_t\fP.
 372 .SS "#define se_table(entry)"
 373 .PP
 374 .PP
 375  This macro retrieves a pointer to the table that the sparse matrix entry is in.
 376 .PP
 377 \fBParameters: \fP
 378 .in +1c
 379 .TP
 380 \fB\fIentry\fP\fP
 381 A pointer to a \fBsmat_entry_t\fP.
 382 .PP
 383 \fBReturns: \fP
 384 .in +1c
 385 A pointer to a \fBsmat_table_t\fP.
 386 .SS "#define se_verify(entry)"
 387 .PP
 388 .PP
 389  This macro verifies that a given pointer actually does point to a sparse matrix entry.
 390 .PP
 391 \fBParameters: \fP
 392 .in +1c
 393 .TP
 394 \fB\fIentry\fP\fP
 395 A pointer to a \fBsmat_entry_t\fP.
 396 .PP
 397 \fBReturns: \fP
 398 .in +1c
 399 Boolean true if \fCentry\fP is a valid sparse matrix entry or false otherwise.
 400 .SS "#define sh_count(head)"
 401 .PP
 402 .PP
 403  This macro retrieves the number of elements in the sparse matrix list rooted at \fChead\fP.
 404 .PP
 405 \fBParameters: \fP
 406 .in +1c
 407 .TP
 408 \fB\fIhead\fP\fP
 409 A pointer to \fBsmat_head_t\fP.
 410 .PP
 411 \fBReturns: \fP
 412 .in +1c
 413 An \fCunsigned long\fP containing a count of the number of elements in the sparse matrix list.
 414 .SS "#define sh_elem(head)"
 415 .PP
 416 .PP
 417  This macro retrieves the position indicator for the sparse matrix head. It will return one of \fBSMAT_LOC_FIRST\fP or \fBSMAT_LOC_SECOND\fP.
 418 .PP
 419 \fBParameters: \fP
 420 .in +1c
 421 .TP
 422 \fB\fIhead\fP\fP
 423 A pointer to \fBsmat_head_t\fP.
 424 .PP
 425 \fBReturns: \fP
 426 .in +1c
 427 An \fBsmat_loc_t\fP.
 428 .SS "#define sh_first(head)"
 429 .PP
 430 .PP
 431  This macro retrieves a pointer to the \fBsmat_entry_t\fP for the first element in the sparse matrix list.
 432 .PP
 433 \fBWarning: \fP
 434 .in +1c
 435 This macro may evaluate the \fChead\fP argument twice.
 436 .PP
 437 \fBParameters: \fP
 438 .in +1c
 439 .TP
 440 \fB\fIhead\fP\fP
 441 A pointer to \fBsmat_head_t\fP.
 442 .PP
 443 \fBReturns: \fP
 444 .in +1c
 445 A pointer to \fBsmat_entry_t\fP.
 446 .SS "#define sh_frozen(head)"
 447 .PP
 448 .PP
 449  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.
 450 .PP
 451 \fBParameters: \fP
 452 .in +1c
 453 .TP
 454 \fB\fIhead\fP\fP
 455 A pointer to a \fBsmat_head_t\fP.
 456 .PP
 457 \fBReturns: \fP
 458 .in +1c
 459 A zero value if the matrix is not frozen or a non-zero value if the matrix is frozen.
 460 .SS "#define sh_last(head)"
 461 .PP
 462 .PP
 463  This macro retrieves a pointer to the \fBsmat_entry_t\fP for the last element in the sparse matrix list.
 464 .PP
 465 \fBWarning: \fP
 466 .in +1c
 467 This macro may evaluate the \fChead\fP argument twice.
 468 .PP
 469 \fBParameters: \fP
 470 .in +1c
 471 .TP
 472 \fB\fIhead\fP\fP
 473 A pointer to \fBsmat_head_t\fP.
 474 .PP
 475 \fBReturns: \fP
 476 .in +1c
 477 A pointer to \fBsmat_entry_t\fP.
 478 .SS "#define sh_object(head)"
 479 .PP
 480 .PP
 481  This macro retrieves a pointer to the object referenced by the sparse matrix list head.
 482 .PP
 483 \fBParameters: \fP
 484 .in +1c
 485 .TP
 486 \fB\fIhead\fP\fP
 487 A pointer to \fBsmat_head_t\fP.
 488 .PP
 489 \fBReturns: \fP
 490 .in +1c
 491 A pointer to \fCvoid\fP.
 492 .SS "#define sh_size(head)"
 493 .PP
 494 .PP
 495  This macro returns the physical size of the memory allocated by the library for this sparse matrix list.
 496 .PP
 497 \fBNote: \fP
 498 .in +1c
 499 The \fBst_size\fP() macro already counts the memory for each list in the table. Summing the results of \fBsh_size\fP() and \fBst_size\fP() will over-count the amount of memory actually in use.
 500 .PP
 501 \fBParameters: \fP
 502 .in +1c
 503 .TP
 504 \fB\fIhead\fP\fP
 505 A pointer to \fBsmat_head_t\fP.
 506 .PP
 507 \fBReturns: \fP
 508 .in +1c
 509 A \fCsize_t\fP.
 510 .SS "#define sh_table(head)"
 511 .PP
 512 .PP
 513  If there are any elements in this sparse matrix list head, this macro will retrieve a pointer to the table in which they reside.
 514 .PP
 515 \fBParameters: \fP
 516 .in +1c
 517 .TP
 518 \fB\fIhead\fP\fP
 519 A pointer to \fBsmat_head_t\fP.
 520 .PP
 521 \fBReturns: \fP
 522 .in +1c
 523 A pointer to \fBsmat_table_t\fP.
 524 .SS "#define sh_verify(head)"
 525 .PP
 526 .PP
 527  This macro verifies that a given pointer actually does point to a sparse matrix head.
 528 .PP
 529 \fBParameters: \fP
 530 .in +1c
 531 .TP
 532 \fB\fIhead\fP\fP
 533 A pointer to a \fBsmat_head_t\fP.
 534 .PP
 535 \fBReturns: \fP
 536 .in +1c
 537 Boolean true if \fChead\fP is a valid sparse matrix head or false otherwise.
 538 .SS "#define st_count(table)"
 539 .PP
 540 .PP
 541  This macro retrieves the total number of items actually in the sparse matrix table.
 542 .PP
 543 \fBParameters: \fP
 544 .in +1c
 545 .TP
 546 \fB\fItable\fP\fP
 547 A pointer to a \fBsmat_table_t\fP.
 548 .PP
 549 \fBReturns: \fP
 550 .in +1c
 551 An \fCunsigned long\fP containing a count of the number of items in the sparse matrix table.
 552 .SS "#define st_extra(table)"
 553 .PP
 554 .PP
 555  This macro retrieves the extra pointer data associated with a particular sparse matrix table.
 556 .PP
 557 \fBParameters: \fP
 558 .in +1c
 559 .TP
 560 \fB\fItable\fP\fP
 561 A pointer to a \fBsmat_table_t\fP.
 562 .PP
 563 \fBReturns: \fP
 564 .in +1c
 565 A pointer to \fCvoid\fP.
 566 .SS "#define st_flags(table)"
 567 .PP
 568 .PP
 569  This macro retrieves the flags associated with the sparse matrix table. Only \fBHASH_FLAG_AUTOGROW\fP and \fBHASH_FLAG_AUTOSHRINK\fP 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.
 570 .PP
 571 \fBParameters: \fP
 572 .in +1c
 573 .TP
 574 \fB\fItable\fP\fP
 575 A pointer to a \fBsmat_table_t\fP.
 576 .PP
 577 \fBReturns: \fP
 578 .in +1c
 579 An \fCunsigned long\fP containing the flags for the sparse matrix table.
 580 .SS "#define st_frozen(table)"
 581 .PP
 582 .PP
 583  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.
 584 .PP
 585 \fBParameters: \fP
 586 .in +1c
 587 .TP
 588 \fB\fItable\fP\fP
 589 A pointer to a \fBsmat_table_t\fP.
 590 .PP
 591 \fBReturns: \fP
 592 .in +1c
 593 A zero value if the matrix is not frozen or a non-zero value if the matrix is frozen.
 594 .SS "#define st_modulus(table)"
 595 .PP
 596 .PP
 597  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.
 598 .PP
 599 \fBParameters: \fP
 600 .in +1c
 601 .TP
 602 \fB\fItable\fP\fP
 603 A pointer to a \fBsmat_table_t\fP.
 604 .PP
 605 \fBReturns: \fP
 606 .in +1c
 607 An \fCunsigned long\fP containing the number of buckets allocated for the sparse matrix table.
 608 .SS "#define st_size(table)"
 609 .PP
 610 .PP
 611  This macro returns the physical size of the memory allocated by the library for this sparse matrix table.
 612 .PP
 613 \fBNote: \fP
 614 .in +1c
 615 The \fBst_size\fP() macro already counts the memory for each list in the table. Summing the results of \fBsh_size\fP() and \fBst_size\fP() will over-count the amount of memory actually in use.
 616 .PP
 617 \fBParameters: \fP
 618 .in +1c
 619 .TP
 620 \fB\fItable\fP\fP
 621 A pointer to a \fBsmat_table_t\fP.
 622 .PP
 623 \fBReturns: \fP
 624 .in +1c
 625 A \fCsize_t\fP.
 626 .SS "#define st_verify(table)"
 627 .PP
 628 .PP
 629  This macro verifies that a given pointer actually does point to a sparse matrix table.
 630 .PP
 631 \fBParameters: \fP
 632 .in +1c
 633 .TP
 634 \fB\fItable\fP\fP
 635 A pointer to a \fBsmat_table_t\fP.
 636 .PP
 637 \fBReturns: \fP
 638 .in +1c
 639 Boolean true if \fCtable\fP is a valid sparse matrix table or false otherwise.
 640 .SH "TYPEDEF DOCUMENTATION"
 641 .PP
 642 .SS "typedef unsigned long(* smat_comp_t)(\fBdb_key_t\fP *, \fBsmat_entry_t\fP *)"
 643 .PP
 644 .PP
 645  This function pointer references a callback used by \fBsh_find\fP(). It should return 0 if the sparse matrix entry represented by the second argument matches the key passed as the first argument.
 646 .SS "typedef struct _smat_entry_s smat_entry_t"
 647 .PP
 648 .PP
 649  This structure is allocated by the library and represents a single element in a sparse matrix.
 650 .SS "typedef struct _smat_head_s smat_head_t"
 651 .PP
 652 .PP
 653  This structure is the head of a linked list of sparse matrix entries.
 654 .SS "typedef unsigned long(* smat_iter_t)(\fBsmat_table_t\fP *, \fBsmat_entry_t\fP *, void *)"
 655 .PP
 656 .PP
 657  This function pointer references a callback used by \fBst_iter\fP(), \fBst_flush\fP(), \fBsh_iter\fP(), 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.
 658 .SS "typedef enum \fB_smat_loc_e\fP smat_loc_t"
 659 .PP
 660 .PP
 661  See the documentation for the enumeration \fB_smat_loc_e\fP.
 662 .SS "typedef unsigned long(* smat_resize_t)(\fBsmat_table_t\fP *, unsigned long)"
 663 .PP
 664 .PP
 665  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.
 666 .SS "typedef struct _smat_table_s smat_table_t"
 667 .PP
 668 .PP
 669  This structure is the basis of all sparse matrices maintained by this library.
 670 .SH "ENUMERATION TYPE DOCUMENTATION"
 671 .PP
 672 .SS "enum _smat_loc_e"
 673 .PP
 674 .PP
 675  This enumeration is used to specify whether an element is a row or column element. It should be referenced by the typedef \fBsmat_loc_t\fP.
 676 .PP
 677 \fBEnumeration values:\fP
 678 .in +1c
 679 .TP
 680 \fB\fISMAT_LOC_FIRST\fP \fP
 681 First entry (``row'').
 682 .TP
 683 \fB\fISMAT_LOC_SECOND\fP \fP
 684 Second entry (``column'').
 685 .SH "FUNCTION DOCUMENTATION"
 686 .PP
 687 .SS "unsigned long sh_find (\fBsmat_head_t\fP * head, \fBsmat_entry_t\fP ** elem_p, \fBsmat_comp_t\fP comp_func, \fBsmat_entry_t\fP * start, \fBdb_key_t\fP * key)"
 688 .PP
 689 .PP
 690  This function iterates through the given row or column of a sparse matrix looking for an element that matches the given \fCkey\fP.
 691 .PP
 692 \fBParameters: \fP
 693 .in +1c
 694 .TP
 695 \fB\fIhead\fP\fP
 696 A pointer to a \fBsmat_head_t\fP.
 697 .TP
 698 \fB\fIelem_p\fP\fP
 699 A pointer to a pointer to a \fBsmat_entry_t\fP. This is a result pramater. \fCNULL\fP is an invalid value.
 700 .TP
 701 \fB\fIcomp_func\fP\fP
 702 A pointer to a comparison function used to compare the key to a particular entry. See the documentation for \fBsmat_comp_t\fP for more information.
 703 .TP
 704 \fB\fIstart\fP\fP
 705 A pointer to a \fBsmat_entry_t\fP describing where in the row or column to start. If \fCNULL\fP is passed, the beginning of the row or column will be assumed.
 706 .TP
 707 \fB\fIkey\fP\fP
 708 A key to search for.
 709 .PP
 710 \fBReturn values: \fP
 711 .in +1c
 712 .TP
 713 \fB\fIDB_ERR_BADARGS\fP\fP
 714 An argument was invalid.
 715 .TP
 716 \fB\fIDB_ERR_WRONGTABLE\fP\fP
 717 \fCstart\fP is not in this row or column.
 718 .TP
 719 \fB\fIDB_ERR_NOENTRY\fP\fP
 720 No matching entry was found.
 721 .SS "unsigned long sh_init (\fBsmat_head_t\fP * head, \fBsmat_loc_t\fP elem, void * object)"
 722 .PP
 723 .PP
 724  This function dynamically initializes a sparse matrix row or column linked list head. The \fCelem\fP argument specifies whether the object is to be associated with a \fBSMAT_LOC_FIRST\fP list or a \fBSMAT_LOC_SECOND\fP list.
 725 .PP
 726 \fBParameters: \fP
 727 .in +1c
 728 .TP
 729 \fB\fIhead\fP\fP
 730 A pointer to a \fBsmat_head_t\fP to be initialized.
 731 .TP
 732 \fB\fIelem\fP\fP
 733 Either \fBSMAT_LOC_FIRST\fP or \fBSMAT_LOC_SECOND\fP.
 734 .TP
 735 \fB\fIobject\fP\fP
 736 A pointer to the object containing the sparse matrix row or column head.
 737 .PP
 738 \fBReturn values: \fP
 739 .in +1c
 740 .TP
 741 \fB\fIDB_ERR_BADARGS\fP\fP
 742 An invalid argument was given.
 743 .SS "unsigned long sh_iter (\fBsmat_head_t\fP * head, \fBsmat_iter_t\fP iter_func, void * extra)"
 744 .PP
 745 .PP
 746  This function iterates over a row or column of a sparse matrix, executing the given \fCiter_func\fP for each entry.
 747 .PP
 748 \fBParameters: \fP
 749 .in +1c
 750 .TP
 751 \fB\fIhead\fP\fP
 752 A pointer to a \fBsmat_head_t\fP.
 753 .TP
 754 \fB\fIiter_func\fP\fP
 755 A pointer to a callback function used to perform user-specified actions on an entry in a row or column of a sparse matrix. \fCNULL\fP is an invalid value. See the documentation for \fBsmat_iter_t\fP for more information.
 756 .TP
 757 \fB\fIextra\fP\fP
 758 A \fCvoid\fP pointer that will be passed to \fCiter_func\fP.
 759 .PP
 760 \fBReturn values: \fP
 761 .in +1c
 762 .TP
 763 \fB\fIDB_ERR_BADARGS\fP\fP
 764 An argument was invalid.
 765 .SS "unsigned long sh_move (\fBsmat_head_t\fP * head, \fBsmat_entry_t\fP * elem, \fBlink_loc_t\fP loc, \fBsmat_entry_t\fP * elem2)"
 766 .PP
 767 .PP
 768  This function allows the specified entry to be shifted within the linked list describing the row or column. It is very similar to the \fBll_move\fP() function.
 769 .PP
 770 \fBParameters: \fP
 771 .in +1c
 772 .TP
 773 \fB\fIhead\fP\fP
 774 A pointer to a \fBsmat_head_t\fP.
 775 .TP
 776 \fB\fIelem\fP\fP
 777 A pointer to the \fBsmat_entry_t\fP describing the entry to be moved.
 778 .TP
 779 \fB\fIloc\fP\fP
 780 A \fBlink_loc_t\fP indicating where the entry should be moved to.
 781 .TP
 782 \fB\fIelem2\fP\fP
 783 A pointer to a \fBsmat_entry_t\fP describing another entry in the list if \fCloc\fP is \fBLINK_LOC_BEFORE\fP or \fBLINK_LOC_AFTER\fP.
 784 .PP
 785 \fBReturn values: \fP
 786 .in +1c
 787 .TP
 788 \fB\fIDB_ERR_BADARGS\fP\fP
 789 An argument was invalid.
 790 .TP
 791 \fB\fIDB_ERR_BUSY\fP\fP
 792 \fCelem\fP and \fCelem2\fP are the same entry.
 793 .TP
 794 \fB\fIDB_ERR_WRONGTABLE\fP\fP
 795 \fCelem\fP or \fCelem2\fP are in a different row or column.
 796 .TP
 797 \fB\fIDB_ERR_UNUSED\fP\fP
 798 \fCelem\fP or \fCelem2\fP are not in any row or column.
 799 .SS "unsigned long smat_cleanup (void)"
 800 .PP
 801 .PP
 802  This function frees all smat_entry_t objects on the internal free list. It is always successful and returns 0.
 803 .SS "unsigned long smat_freemem (void)"
 804 .PP
 805 .PP
 806  This function returns the amount of memory being used by the internal free list of smat_entry_t objects.
 807 .PP
 808 \fBReturns: \fP
 809 .in +1c
 810 A number indicating the size, in bytes, of the memory allocated for smat_entry_t objects on the free list.
 811 .SS "unsigned long st_add (\fBsmat_table_t\fP * table, \fBsmat_entry_t\fP ** entry_p, \fBsmat_head_t\fP * head1, \fBlink_loc_t\fP loc1, \fBsmat_entry_t\fP * ent1, \fBsmat_head_t\fP * head2, \fBlink_loc_t\fP loc2, \fBsmat_entry_t\fP * ent2)"
 812 .PP
 813 .PP
 814  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 \fBsmat_entry_t\fP and return it through the \fCentry_p\fP result parameter.
 815 .PP
 816 \fBParameters: \fP
 817 .in +1c
 818 .TP
 819 \fB\fItable\fP\fP
 820 A pointer to a \fBsmat_table_t\fP.
 821 .TP
 822 \fB\fIentry_p\fP\fP
 823 A pointer to a pointer to a \fBsmat_entry_t\fP. This is a result parameter. If \fCNULL\fP is passed, the addition will be performed and an appropriate error code returned.
 824 .TP
 825 \fB\fIhead1\fP\fP
 826 A pointer to a \fBsmat_head_t\fP representing a \fBSMAT_LOC_FIRST\fP sparse matrix list.
 827 .TP
 828 \fB\fIloc1\fP\fP
 829 A \fBlink_loc_t\fP indicating where the entry should be added for \fChead1\fP.
 830 .TP
 831 \fB\fIent1\fP\fP
 832 A pointer to a \fBsmat_entry_t\fP describing another element in the list represented by \fChead1\fP if \fCloc1\fP is \fBLINK_LOC_BEFORE\fP or \fBLINK_LOC_AFTER\fP.
 833 .TP
 834 \fB\fIhead2\fP\fP
 835 A pointer to a \fBsmat_head_t\fP representing a \fBSMAT_LOC_SECOND\fP sparse matrix list.
 836 .TP
 837 \fB\fIloc2\fP\fP
 838 A \fBlink_loc_t\fP indicating where the entry should be added for \fChead2\fP.
 839 .TP
 840 \fB\fIent2\fP\fP
 841 A pointer to a \fBsmat_entry_t\fP describing another element in the list represented by \fChead2\fP if \fCloc2\fP is \fBLINK_LOC_BEFORE\fP or \fBLINK_LOC_AFTER\fP.
 842 .PP
 843 \fBReturn values: \fP
 844 .in +1c
 845 .TP
 846 \fB\fIDB_ERR_BADARGS\fP\fP
 847 An argument was invalid.
 848 .TP
 849 \fB\fIDB_ERR_BUSY\fP\fP
 850 One of the arguments is already in the table.
 851 .TP
 852 \fB\fIDB_ERR_FROZEN\fP\fP
 853 The table is currently frozen.
 854 .TP
 855 \fB\fIDB_ERR_NOTABLE\fP\fP
 856 The bucket table has not been allocated and automatic growth is not enabled.
 857 .TP
 858 \fB\fIDB_ERR_WRONGTABLE\fP\fP
 859 One of the arguments was not in the proper table or list.
 860 .TP
 861 \fB\fIDB_ERR_UNUSED\fP\fP
 862 One of the \fCent\fP arguments is not presently in a list.
 863 .TP
 864 \fB\fIDB_ERR_UNRECOVERABLE\fP\fP
 865 An unrecoverable error occurred while resizing the table.
 866 .TP
 867 \fB\fIENOMEM\fP\fP
 868 No memory could be allocated for the \fBsmat_entry_t\fP structure.
 869 .SS "unsigned long st_find (\fBsmat_table_t\fP * table, \fBsmat_entry_t\fP ** entry_p, \fBsmat_head_t\fP * head1, \fBsmat_head_t\fP * head2)"
 870 .PP
 871 .PP
 872  This function looks up the entry matching the given \fChead1\fP and \fChead2\fP.
 873 .PP
 874 \fBParameters: \fP
 875 .in +1c
 876 .TP
 877 \fB\fItable\fP\fP
 878 A pointer to a \fBsmat_table_t\fP.
 879 .TP
 880 \fB\fIentry_p\fP\fP
 881 A pointer to a pointer to a \fBsmat_entry_t\fP. This is a result parameter. If \fCNULL\fP is passed, the lookup will be performed and an appropriate error code returned.
 882 .TP
 883 \fB\fIhead1\fP\fP
 884 A pointer to a \fBsmat_head_t\fP initialized to \fBSMAT_LOC_FIRST\fP.
 885 .TP
 886 \fB\fIhead2\fP\fP
 887 A pointer to a \fBsmat_head_t\fP initialized to \fBSMAT_LOC_SECOND\fP.
 888 .PP
 889 \fBReturn values: \fP
 890 .in +1c
 891 .TP
 892 \fB\fIDB_ERR_BADARGS\fP\fP
 893 An argument was invalid.
 894 .TP
 895 \fB\fIDB_ERR_WRONGTABLE\fP\fP
 896 One or both of \fChead1\fP or \fChead2\fP are not referenced in this table.
 897 .TP
 898 \fB\fIDB_ERR_NOENTRY\fP\fP
 899 No matching entry was found.
 900 .SS "unsigned long st_flush (\fBsmat_table_t\fP * table, \fBsmat_iter_t\fP flush_func, void * extra)"
 901 .PP
 902 .PP
 903  This function flushes a sparse matrix--that is, it removes each entry from the matrix. If a \fCflush_func\fP is specified, it will be called on the entry after it has been removed from the table, and may safely call \fCfree()\fP.
 904 .PP
 905 \fBParameters: \fP
 906 .in +1c
 907 .TP
 908 \fB\fItable\fP\fP
 909 A pointer to a \fBsmat_table_t\fP.
 910 .TP
 911 \fB\fIflush_func\fP\fP
 912 A pointer to a callback function used to perform user-specified actions on an entry after removing it from the table. May be \fCNULL\fP. See the documentation for \fBsmat_iter_t\fP for more information.
 913 .TP
 914 \fB\fIextra\fP\fP
 915 A \fCvoid\fP pointer that will be passed to \fCiter_func\fP.
 916 .PP
 917 \fBReturn values: \fP
 918 .in +1c
 919 .TP
 920 \fB\fIDB_ERR_BADARGS\fP\fP
 921 An argument was invalid.
 922 .TP
 923 \fB\fIDB_ERR_FROZEN\fP\fP
 924 The sparse matrix is frozen.
 925 .SS "unsigned long st_free (\fBsmat_table_t\fP * table)"
 926 .PP
 927 .PP
 928  This function releases the memory used by the bucket table of the empty hash table associated with a sparse matrix.
 929 .PP
 930 \fBParameters: \fP
 931 .in +1c
 932 .TP
 933 \fB\fItable\fP\fP
 934 A pointer to a \fBsmat_table_t\fP.
 935 .PP
 936 \fBReturn values: \fP
 937 .in +1c
 938 .TP
 939 \fB\fIDB_ERR_BADARGS\fP\fP
 940 An invalid argument was given.
 941 .TP
 942 \fB\fIDB_ERR_FROZEN\fP\fP
 943 The table is frozen.
 944 .TP
 945 \fB\fIDB_ERR_NOTEMPTY\fP\fP
 946 The table is not empty.
 947 .SS "unsigned long st_init (\fBsmat_table_t\fP * table, unsigned long flags, \fBsmat_resize_t\fP resize, void * extra, unsigned long init_mod)"
 948 .PP
 949 This function dynamically initializes a sparse matrix table.
 950 .PP
 951 \fBParameters: \fP
 952 .in +1c
 953 .TP
 954 \fB\fItable\fP\fP
 955 A pointer to a \fBsmat_table_t\fP to be initialized.
 956 .TP
 957 \fB\fIflags\fP\fP
 958 A bit-wise OR of \fBHASH_FLAG_AUTOGROW\fP and \fBHASH_FLAG_AUTOSHRINK\fP. If neither behavior is desired, use 0.
 959 .TP
 960 \fB\fIresize\fP\fP
 961 A \fBhash_resize_t\fP function pointer for determining whether resizing is permitted and/or for notification of the resize.
 962 .TP
 963 \fB\fIextra\fP\fP
 964 Extra pointer data that should be associated with the sparse matrix table.
 965 .TP
 966 \fB\fIinit_mod\fP\fP
 967 An initial modulus for the table. This will presumably be extracted by \fBst_modulus\fP() in a previous invocation of the application. A 0 value is valid.
 968 .PP
 969 \fBReturn values: \fP
 970 .in +1c
 971 .TP
 972 \fB\fIDB_ERR_BADARGS\fP\fP
 973 An invalid argument was given.
 974 .TP
 975 \fB\fIENOMEM\fP\fP
 976 Unable to allocate memory.
 977 .SS "unsigned long st_iter (\fBsmat_table_t\fP * table, \fBsmat_iter_t\fP iter_func, void * extra)"
 978 .PP
 979 .PP
 980  This function iterates over every entry in a sparse matrix (in an unspecified order), executing the given \fCiter_func\fP on each entry.
 981 .PP
 982 \fBParameters: \fP
 983 .in +1c
 984 .TP
 985 \fB\fItable\fP\fP
 986 A pointer to a \fBsmat_table_t\fP.
 987 .TP
 988 \fB\fIiter_func\fP\fP
 989 A pointer to a callback function used to perform user-specified actions on an entry in a sparse matrix. \fCNULL\fP is an invalid value. See the documentation for \fBsmat_iter_t\fP for more information.
 990 .TP
 991 \fB\fIextra\fP\fP
 992 A \fCvoid\fP pointer that will be passed to \fCiter_func\fP.
 993 .PP
 994 \fBReturn values: \fP
 995 .in +1c
 996 .TP
 997 \fB\fIDB_ERR_BADARGS\fP\fP
 998 An argument was invalid.
 999 .TP
1000 \fB\fIDB_ERR_FROZEN\fP\fP
1001 The sparse matrix is frozen.
1002 .SS "unsigned long st_remove (\fBsmat_table_t\fP * table, \fBsmat_entry_t\fP * entry)"
1003 .PP
1004 .PP
1005  This function removes the given entry from the specified sparse matrix.
1006 .PP
1007 \fBParameters: \fP
1008 .in +1c
1009 .TP
1010 \fB\fItable\fP\fP
1011 A pointer to a \fBsmat_table_t\fP.
1012 .TP
1013 \fB\fIentry\fP\fP
1014 A pointer to a \fBsmat_entry_t\fP to be removed from the table.
1015 .PP
1016 \fBReturn values: \fP
1017 .in +1c
1018 .TP
1019 \fB\fIDB_ERR_BADARGS\fP\fP
1020 An invalid argument was given.
1021 .TP
1022 \fB\fIDB_ERR_WRONGTABLE\fP\fP
1023 Entry is not in this sparse matrix.
1024 .TP
1025 \fB\fIDB_ERR_UNRECOVERABLE\fP\fP
1026 An unrecoverable error occurred while removing the entry from the table.
1027 .SS "unsigned long st_resize (\fBsmat_table_t\fP * table, unsigned long new_size)"
1028 .PP
1029 .PP
1030  This function resizes the hash table associated with a sparse matrix based on the \fCnew_size\fP parameter. See the documentation for \fBht_resize\fP() for more information.
1031 .PP
1032 \fBParameters: \fP
1033 .in +1c
1034 .TP
1035 \fB\fItable\fP\fP
1036 A pointer to a \fBsmat_table_t\fP.
1037 .TP
1038 \fB\fInew_size\fP\fP
1039 A new size value for the table.
1040 .PP
1041 \fBReturn values: \fP
1042 .in +1c
1043 .TP
1044 \fB\fIDB_ERR_BADARGS\fP\fP
1045 An argument was invalid.
1046 .TP
1047 \fB\fIDB_ERR_FROZEN\fP\fP
1048 The table is currently frozen.
1049 .TP
1050 \fB\fIDB_ERR_UNRECOVERABLE\fP\fP
1051 A catastrophic error was encountered. The table is now unusable.
1052 .TP
1053 \fB\fIENOMEM\fP\fP
1054 No memory could be allocated for the new bucket table.