1/* MANSEC = Sys */ 2/* SUBMANSEC = PetscH */ 3 4This file is processed by make allmanpages in $PETSC_DIR/makefile to create manual pages 5for the types and macros created by PETSC_HASH_MAP(). For example, PetscHMAPIJ. 6 7/*S 8 PetscHMap<T> - Hash table map with a key of <KeyType> 9 10 Synopsis: 11 typedef khash_t(HMap<T>) *PetscHMap<T>; 12 13 Level: developer 14 15.seealso: `PETSC_HASH_MAP()`, `PetscHMap<T>Create()`, `PETSC_HASH_SET()`, `PetscHSet<T>Create()` 16S*/ 17typedef struct _PetscHash<T> PetscHMap<T>; 18 19/*MC 20 PetscHMap<T>Create - Create a hash table 21 22 Synopsis: 23 #include <petsc/private/hashmap<t>.h> 24 PetscErrorCode PetscHMap<T>Create(PetscHMap<T> *ht) 25 26 Output Parameter: 27. ht - The hash table 28 29 Level: developer 30 31.seealso: `PetscHMap<T>CreateWithSize()`, `PetscHMap<T>Destroy()` 32M*/ 33 34/*MC 35 PetscHMap<T>CreateWithSize - Create a hash table with a given initial size 36 37 Synopsis: 38 #include <petsc/private/hashmap<t>.h> 39 PetscErrorCode PetscHMap<T>CreateWithSize(PetscInt n, PetscHMap<T> *ht) 40 41 Input Parameter: 42. n - The size of the hash table 43 44 Output Parameter: 45. ht - The hash table 46 47 Level: developer 48 49 Note: 50 `n` must be non-negative. 51 52.seealso: `PetscHMap<T>Create()`, `PetscHMap<T>Destroy()` 53M*/ 54 55/*MC 56 PetscHMap<T>Destroy - Destroy a hash table 57 58 Synopsis: 59 #include <petsc/private/hashmap<t>.h> 60 PetscErrorCode PetscHMap<T>Destroy(PetscHMap<T> *ht) 61 62 Input Parameter: 63. ht - The hash table 64 65 Level: developer 66 67.seealso: `PetscHMap<T>Create()`, `PetscHMap<T>CreateWithSize()` 68M*/ 69 70/*MC 71 PetscHMap<T>Reset - Reset a hash table 72 73 Synopsis: 74 #include <petsc/private/hashmap<t>.h> 75 PetscErrorCode PetscHMap<T>Reset(PetscHMap<T> ht) 76 77 Input Parameter: 78. ht - The hash table 79 80 Level: developer 81 82.seealso: `PetscHMap<T>Clear()` 83M*/ 84 85/*MC 86 PetscHMap<T>Duplicate - Duplicate a hash table 87 88 Synopsis: 89 #include <petsc/private/hashmap<t>.h> 90 PetscErrorCode PetscHMap<T>Duplicate(PetscHMap<T> ht, PetscHMap<T> *hd) 91 92 Input Parameter: 93. ht - The source hash table 94 95 Output Parameter: 96. ht - The duplicated hash table 97 98 Level: developer 99 100.seealso: `PetscHMap<T>Create()` 101M*/ 102 103/*MC 104 PetscHMap<T>Clear - Clear a hash table 105 106 Synopsis: 107 #include <petsc/private/hashmap<t>.h> 108 PetscErrorCode PetscHMap<T>Clear(PetscHMap<T> ht) 109 110 Input Parameter: 111. ht - The hash table 112 113 Level: developer 114 115.seealso: `PetscHMap<T>Reset()` 116M*/ 117 118/*MC 119 PetscHMap<T>Resize - Set the number of buckets in a hash table 120 121 Synopsis: 122 #include <petsc/private/hashmap<t>.h> 123 PetscErrorCode PetscHMap<T>Resize(PetscHMap<T> ht, PetscInt nb) 124 125 Input Parameters: 126+ ht - The hash table 127- nb - The number of buckets 128 129 Level: developer 130 131.seealso: `PetscHMap<T>Create()` 132M*/ 133 134/*MC 135 PetscHMap<T>GetSize - Get the number of entries in a hash table 136 137 Synopsis: 138 #include <petsc/private/hashmap<t>.h> 139 PetscErrorCode PetscHMap<T>GetSize(PetscHMap<T> ht, PetscInt *n) 140 141 Input Parameter: 142. ht - The hash table 143 144 Output Parameter: 145. n - The number of entries 146 147 Level: developer 148 149.seealso: `PetscHMap<T>Resize()` 150M*/ 151 152/*MC 153 PetscHMap<T>GetCapacity - Get the current size of the array in the hash table 154 155 Synopsis: 156 #include <petsc/private/hashmap<t>.h> 157 PetscErrorCode PetscHMap<T>GetCapacity(PetscHMap<T> ht, PetscInt *n) 158 159 Input Parameter: 160. ht - The hash table 161 162 Output Parameter: 163. n - The capacity 164 165 Level: developer 166 167.seealso: `PetscHMap<T>Resize()`, `PetscHMap<T>GetSize()` 168M*/ 169 170/*MC 171 PetscHMap<T>Has - Query for a key in the hash table 172 173 Synopsis: 174 #include <petsc/private/hashmap<t>.h> 175 PetscErrorCode PetscHMap<T>Has(PetscHMap<T> ht, <KeyType> key, PetscBool *has) 176 177 Input Parameters: 178+ ht - The hash table 179- key - The key 180 181 Output Parameter: 182. has - Boolean indicating whether key is in the hash table 183 184 Level: developer 185 186.seealso: `PetscHMap<T>Get()`, `PetscHMap<T>GetWithDefault()`, `PetscHMap<T>Set()`, 187`PetscHMap<T>SetWithMode()`, `PetscHMap<T>Find()` 188M*/ 189 190/*MC 191 PetscHMap<T>Get - Get the value for a key in the hash table 192 193 Synopsis: 194 #include <petsc/private/hashmap<t>.h> 195 PetscErrorCode PetscHMap<T>Get(PetscHMap<T> ht, <KeyType> key, <ValType> *val) 196 197 Input Parameters: 198+ ht - The hash table 199- key - The key 200 201 Output Parameter: 202. val - The value 203 204 Level: developer 205 206.seealso: `PetscHMap<T>Set()`, `PetscHMap<T>SetWithMode()`, `PetscHMap<T>IterGet()`, 207`PetscHMap<T>GetWithDefault()` 208M*/ 209 210/*MC 211 PetscHMap<T>GetWithDefault - Get the value for a key in the hash table but override the default 212 value returned if the key was not found 213 214 Synopsis: 215 #include <petsc/private/hashmap<t>.h> 216 PetscErrorCode PetscHMap<T>GetWithDefault(PetscHMap<T> ht, <KeyType> key, <ValType> default_val, <ValType> *val) 217 218 Input Parameters: 219+ ht - The hash table 220. key - The key 221- default_val - The default value to set `val` to if `key` was not found 222 223 Output Parameter: 224. val - The value 225 226 Level: developer 227 228.seealso: `PetscHMap<T>Get()`, `PetscHMap<T>Set()`, `PetscHMap<T>SetWithMode()`, `PetscHMap<T>IterGet()` 229M*/ 230 231 232/*MC 233 PetscHMap<T>Set - Set a (key,value) entry in the hash table 234 235 Synopsis: 236 #include <petsc/private/hashmap<t>.h> 237 PetscErrorCode PetscHMap<T>Set(PetscHMap<T> ht, <KeyType> key, <ValType> val) 238 239 Input Parameters: 240+ ht - The hash table 241. key - The key 242- val - The value 243 244 Level: developer 245 246.seealso: `PetscHMap<T>Get()`, `PetscHMap<T>SetWithMode()`, `PetscHMap<T>GetWithDefault()`, 247`PetscHMap<T>IterSet()` 248M*/ 249 250/*MC 251 PetscHMap<T>SetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode` 252 253 Synopsis: 254 #include <petsc/private/hashmap<t>.h> 255 PetscErrorCode PetscHMap<T>SetWithMode(PetscHMap<T> ht, <KeyType> key, <ValType> val, InsertMode mode) 256 257 Input Parameters: 258+ ht - The hash table 259. key - The key 260. val - The value 261- mode - The insertion mode 262 263 Level: developer 264 265 Notes: 266 `mode` may be any of the following\: 267 - `INSERT_VALUES`\: this routine behaves identically to `PetscHMap<T>Set()`. 268 - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`) 269 is inserted into `ht` as-if-by `INSERT_VALUES`. 270 - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the 271 current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by 272 `INSERT_VALUES`. 273 - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the 274 current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by 275 `INSERT_VALUES`. 276 277 All other `InsertMode` values raise an error. 278 279 Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type 280 it is not available by default for all PETSc hash table instantiations. If a particular 281 instantiation supports this routine it must define `PETSC_HMAP<T>_HAVE_EXTENDED_API` to 282 `1`. 283 284.seealso: `PetscHMap<T>Set()`, `PetscHMap<T>Get()`, `PetscHMap<T>GetWithDefault()`, 285`PetscHMap<T>IterSet()` 286M*/ 287 288/*MC 289 PetscHMap<T>Del - Remove a key and its value from the hash table 290 291 Synopsis: 292 #include <petsc/private/hashmap<t>.h> 293 PetscErrorCode PetscHMap<T>Del(PetscHMap<T> ht,<KeyType> key) 294 295 Input Parameters: 296+ ht - The hash table 297- key - The key 298 299 Level: developer 300 301.seealso: `PetscHMap<T>Has()`, `PetscHMap<T>IterDel()` 302M*/ 303 304/*MC 305 PetscHMap<T>QuerySet - Query and set a (key,value) entry in the hash table 306 307 Synopsis: 308 #include <petsc/private/hashmap<t>.h> 309 PetscErrorCode PetscHMap<T>QuerySet(PetscHMap<T> ht, <KeyType> key, <ValType> val, PetscBool *missing) 310 311 Input Parameters: 312+ ht - The hash table 313. key - The key 314- val - The value 315 316 Output Parameter: 317. missing - Boolean indicating whether the key was missing 318 319 Level: developer 320 321.seealso: `PetscHMap<T>QueryDel()`, `PetscHMap<T>Set()`, `PetscHMap<T>SetWithMode()` 322M*/ 323 324/*MC 325 PetscHMap<T>QueryDel - Query and remove a (key,value) entry from the hash table 326 327 Synopsis: 328 #include <petsc/private/hashmap<t>.h> 329 PetscErrorCode PetscHMap<T>QueryDel(PetscHMap<T> ht, <KeyType> key, PetscBool *present) 330 331 Input Parameters: 332+ ht - The hash table 333- key - The key 334 335 Output Parameter: 336. present - Boolean indicating whether the key was present 337 338 Level: developer 339 340.seealso: `PetscHMap<T>QuerySet()`, `PetscHMap<T>Del()` 341M*/ 342 343/*MC 344 PetscHMap<T>Find - Query for key in the hash table 345 346 Synopsis: 347 #include <petsc/private/hashmap<t>.h> 348 PetscErrorCode PetscHMap<T>Find(PetscHMap<T> ht, <KeyType> key, PetscHashIter *iter, PetscBool *found) 349 350 Input Parameters: 351+ ht - The hash table 352- key - The key 353 354 Output Parameters: 355+ iter - Iterator referencing the value for key 356- found - Boolean indicating whether the key was present 357 358 Level: developer 359 360.seealso: `PetscHMap<T>IterGet()`, `PetscHMap<T>IterDel()` 361M*/ 362 363/*MC 364 PetscHMap<T>Put - Set a key in the hash table 365 366 Synopsis: 367 #include <petsc/private/hashmap<t>.h> 368 PetscErrorCode PetscHMap<T>Put(PetscHMap<T> ht, <KeyType> key, PetscHashIter *iter, PetscBool *missing) 369 370 Input Parameters: 371+ ht - The hash table 372- key - The key 373 374 Output Parameters: 375+ iter - Iterator referencing the value for key 376- missing - Boolean indicating whether the key was missing 377 378 Level: developer 379 380.seealso: `PetscHMap<T>IterSet()`, `PetscHMap<T>QuerySet()`, `PetscHMap<T>Set()`, 381`PetscHMap<T>SetWithMode()` 382M*/ 383 384/*MC 385 PetscHMap<T>IterGet - Get the value referenced by an iterator in the hash table 386 387 Synopsis: 388 #include <petsc/private/hashmap<t>.h> 389 PetscErrorCode PetscHMap<T>IterGet(PetscHMap<T> ht, PetscHashIter iter, <ValType> *val) 390 391 Input Parameters: 392+ ht - The hash table 393- iter - The iterator 394 395 Output Parameter: 396. val - The value 397 398 Level: developer 399 400.seealso: `PetscHMap<T>Find()`, `PetscHMap<T>Get()`, `PetscHMap<T>GetWithDefault()` 401M*/ 402 403/*MC 404 PetscHMap<T>IterSet - Set the value referenced by an iterator in the hash 405 406 Synopsis: 407 #include <petsc/private/hashmap<t>.h> 408 PetscErrorCode PetscHMap<T>IterSet(PetscHMap<T> ht, PetscHashIter iter, <ValType> val) 409 410 Input Parameters: 411+ ht - The hash table 412. iter - The iterator 413- val - The value 414 415 Level: developer 416 417.seealso: `PetscHMap<T>Put()`, `PetscHMap<T>QuerySet()`, `PetscHMap<T>Set()`, 418`PetscHMap<T>SetWithMode()` 419M*/ 420 421/*MC 422 PetscHMap<T>IterDel - Remove the (key,value) referenced by an iterator from the hash table 423 424 Synopsis: 425 #include <petsc/private/hashmap<t>.h> 426 PetscErrorCode PetscHMap<T>IterDel(PetscHMap<T> ht, PetscHashIter iter) 427 428 Input Parameters: 429+ ht - The hash table 430- iter - The iterator 431 432 Level: developer 433 434.seealso: `PetscHMap<T>Find()`, `PetscHMap<T>QueryDel()`, `PetscHMap<T>Del()` 435M*/ 436 437/*MC 438 PetscHMap<T>GetKeys - Get all keys from a hash table 439 440 Synopsis: 441 #include <petsc/private/hashmap<t>.h> 442 PetscErrorCode PetscHMap<T>GetKeys(PetscHMap<T> ht, PetscInt *off, <KeyType> array[]) 443 444 Input Parameters: 445+ ht - The hash table 446. off - Input offset in array (usually zero) 447- array - Array to put hash table keys in 448 449 Output Parameters: 450+ off - Output offset in array (output offset = input offset + hash table size) 451- array - Array filled with the hash table keys 452 453 Level: developer 454 455.seealso: `PetscHSet<T>GetSize()`, `PetscHMap<T>GetVals()` 456M*/ 457 458/*MC 459 PetscHMap<T>GetVals - Get all values from a hash table 460 461 Synopsis: 462 #include <petsc/private/hashmap<t>.h> 463 PetscErrorCode PetscHMap<T>GetVals(PetscHMap<T> ht, PetscInt *off, <ValType> array[]) 464 465 Input Parameters: 466+ ht - The hash table 467. off - Input offset in array (usually zero) 468- array - Array to put hash table values in 469 470 Output Parameters: 471+ off - Output offset in array (output offset = input offset + hash table size) 472- array - Array filled with the hash table values 473 474 Level: developer 475 476.seealso: `PetscHSet<T>GetSize()`, `PetscHMap<T>GetKeys()` 477M*/ 478 479/*MC 480 PetscHMap<T>GetPairs - Get all (key,value) pairs from a hash table 481 482 Synopsis: 483 #include <petsc/private/hashmap<t>.h> 484 PetscErrorCode PetscHMap<T>GetPairs(PetscHMap<T> ht, PetscInt *off, <KeyType> karray[], <ValType> varray[]) 485 486 Input Parameters: 487+ ht - The hash table 488. off - Input offset in array (usually zero) 489. karray - Array to put hash table keys in 490- varray - Array to put hash table values in 491 492 Output Parameters: 493+ off - Output offset in array (output offset = input offset + hash table size) 494. karray - Array filled with the hash table keys 495- varray - Array filled with the hash table values 496 497 Level: developer 498 499.seealso: `PetscHSet<T>GetSize()`, `PetscHMap<T>GetKeys()`, `PetscHMap<T>GetVals()` 500M*/ 501