1: /* SUBMANSEC = PetscH */

  3: This file is processed by make allmanpages in $PETSC_DIR/makefile to create manual pages
  4: for the types and macros created by PETSC_HASH_MAP(). For example, PetscHMAPIJ.

  6: /*S
  7:   PetscHMapI - Hash table map with a key of PetscInt

  9:   Synopsis:
 10:   typedef khash_t(HMapI) *PetscHMapI;

 12:   Level: developer

 14: .seealso: `PETSC_HASH_MAP()`, `PetscHMapICreate()`, `PETSC_HASH_SET()`, `PetscHSetICreate()`
 15: S*/
 16: typedef struct _PetscHashI PetscHMapI;

 18: /*MC
 19:   PetscHMapICreate - Create a hash table

 21:   Synopsis:
 22: #include <petsc/private/hashmapi.h>
 23:   PetscErrorCode PetscHMapICreate(PetscHMapI *ht)

 25:   Output Parameter:
 26: . ht - The hash table

 28:   Level: developer

 30: .seealso: `PetscHMapICreateWithSize()`, `PetscHMapIDestroy()`
 31: M*/

 33: /*MC
 34:   PetscHMapICreateWithSize - Create a hash table with a given initial size

 36:   Synopsis:
 37: #include <petsc/private/hashmapi.h>
 38:   PetscErrorCode PetscHMapICreateWithSize(PetscInt n, PetscHMapI *ht)

 40:   Input Parameter:
 41: . n - The size of the hash table

 43:   Output Parameter:
 44: . ht - The hash table

 46:   Level: developer

 48:   Note:
 49:   `n` must be non-negative.

 51: .seealso: `PetscHMapICreate()`, `PetscHMapIDestroy()`
 52: M*/

 54: /*MC
 55:   PetscHMapIDestroy - Destroy a hash table

 57:   Synopsis:
 58: #include <petsc/private/hashmapi.h>
 59:   PetscErrorCode PetscHMapIDestroy(PetscHMapI *ht)

 61:   Input Parameter:
 62: . ht - The hash table

 64:   Level: developer

 66: .seealso: `PetscHMapICreate()`, `PetscHMapICreateWithSize()`
 67: M*/

 69: /*MC
 70:   PetscHMapIReset - Reset a hash table

 72:   Synopsis:
 73: #include <petsc/private/hashmapi.h>
 74:   PetscErrorCode PetscHMapIReset(PetscHMapI ht)

 76:   Input Parameter:
 77: . ht - The hash table

 79:   Level: developer

 81: .seealso: `PetscHMapIClear()`
 82: M*/

 84: /*MC
 85:   PetscHMapIDuplicate - Duplicate a hash table

 87:   Synopsis:
 88: #include <petsc/private/hashmapi.h>
 89:   PetscErrorCode PetscHMapIDuplicate(PetscHMapI ht, PetscHMapI *hd)

 91:   Input Parameter:
 92: . ht - The source hash table

 94:   Output Parameter:
 95: . ht - The duplicated hash table

 97:   Level: developer

 99: .seealso: `PetscHMapICreate()`
100: M*/

102: /*MC
103:   PetscHMapIClear - Clear a hash table

105:   Synopsis:
106: #include <petsc/private/hashmapi.h>
107:   PetscErrorCode PetscHMapIClear(PetscHMapI ht)

109:   Input Parameter:
110: . ht - The hash table

112:   Level: developer

114: .seealso: `PetscHMapIReset()`
115: M*/

117: /*MC
118:   PetscHMapIResize - Set the number of buckets in a hash table

120:   Synopsis:
121: #include <petsc/private/hashmapi.h>
122:   PetscErrorCode PetscHMapIResize(PetscHMapI ht, PetscInt nb)

124:   Input Parameters:
125: + ht - The hash table
126: - nb - The number of buckets

128:   Level: developer

130: .seealso: `PetscHMapICreate()`
131: M*/

133: /*MC
134:   PetscHMapIGetSize - Get the number of entries in a hash table

136:   Synopsis:
137: #include <petsc/private/hashmapi.h>
138:   PetscErrorCode PetscHMapIGetSize(PetscHMapI ht, PetscInt *n)

140:   Input Parameter:
141: . ht - The hash table

143:   Output Parameter:
144: . n - The number of entries

146:   Level: developer

148: .seealso: `PetscHMapIResize()`
149: M*/

151: /*MC
152:   PetscHMapIGetCapacity - Get the current size of the array in the hash table

154:   Synopsis:
155: #include <petsc/private/hashmapi.h>
156:   PetscErrorCode PetscHMapIGetCapacity(PetscHMapI ht, PetscInt *n)

158:   Input Parameter:
159: . ht - The hash table

161:   Output Parameter:
162: . n - The capacity

164:   Level: developer

166: .seealso: `PetscHMapIResize()`, `PetscHMapIGetSize()`
167: M*/

169: /*MC
170:   PetscHMapIHas - Query for a key in the hash table

172:   Synopsis:
173: #include <petsc/private/hashmapi.h>
174:   PetscErrorCode PetscHMapIHas(PetscHMapI ht, PetscInt key, PetscBool *has)

176:   Input Parameters:
177: + ht  - The hash table
178: - key - The key

180:   Output Parameter:
181: . has - Boolean indicating whether key is in the hash table

183:   Level: developer

185: .seealso: `PetscHMapIGet()`, `PetscHMapIGetWithDefault()`, `PetscHMapISet()`,
186: `PetscHMapISetWithMode()`, `PetscHMapIFind()`
187: M*/

189: /*MC
190:   PetscHMapIGet - Get the value for a key in the hash table

192:   Synopsis:
193: #include <petsc/private/hashmapi.h>
194:   PetscErrorCode PetscHMapIGet(PetscHMapI ht, PetscInt key,  *val)

196:   Input Parameters:
197: + ht  - The hash table
198: - key - The key

200:   Output Parameter:
201: . val - The value

203:   Level: developer

205: .seealso: `PetscHMapISet()`, `PetscHMapISetWithMode()`, `PetscHMapIIterGet()`,
206: `PetscHMapIGetWithDefault()`
207: M*/

209: /*MC
210:   PetscHMapIGetWithDefault - Get the value for a key in the hash table but override the default
211:   value returned if the key was not found

213:   Synopsis:
214: #include <petsc/private/hashmapi.h>
215:   PetscErrorCode PetscHMapIGetWithDefault(PetscHMapI ht, PetscInt key,  default_val,  *val)

217:   Input Parameters:
218: + ht          - The hash table
219: . key         - The key
220: - default_val - The default value to set `val` to if `key` was not found

222:   Output Parameter:
223: . val - The value

225:   Level: developer

227: .seealso: `PetscHMapIGet()`, `PetscHMapISet()`, `PetscHMapISetWithMode()`, `PetscHMapIIterGet()`
228: M*/


231: /*MC
232:   PetscHMapISet - Set a (key,value) entry in the hash table

234:   Synopsis:
235: #include <petsc/private/hashmapi.h>
236:   PetscErrorCode PetscHMapISet(PetscHMapI ht, PetscInt key,  val)

238:   Input Parameters:
239: + ht  - The hash table
240: . key - The key
241: - val - The value

243:   Level: developer

245: .seealso: `PetscHMapIGet()`, `PetscHMapISetWithMode()`, `PetscHMapIGetWithDefault()`,
246: `PetscHMapIIterSet()`
247: M*/

249: /*MC
250:   PetscHMapISetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode`

252:   Synopsis:
253: #include <petsc/private/hashmapi.h>
254:   PetscErrorCode PetscHMapISetWithMode(PetscHMapI ht, PetscInt key,  val, InsertMode mode)

256:   Input Parameters:
257: + ht   - The hash table
258: . key  - The key
259: . val  - The value
260: - mode - The insertion mode

262:   Level: developer

264:   Notes:
265:   `mode` may be any of the following\:
266:   - `INSERT_VALUES`\: this routine behaves identically to `PetscHMapISet()`.
267:   - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`)
268:                    is inserted into `ht` as-if-by `INSERT_VALUES`.
269:   - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the
270:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
271:                    `INSERT_VALUES`.
272:   - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the
273:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
274:                    `INSERT_VALUES`.

276:    All other `InsertMode` values raise an error.

278:    Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type
279:    it is not available by default for all PETSc hash table instantiations. If a particular
280:    instantiation supports this routine it must define `PETSC_HMAPI_HAVE_EXTENDED_API` to
281:    `1`.

283: .seealso: `PetscHMapISet()`, `PetscHMapIGet()`, `PetscHMapIGetWithDefault()`,
284: `PetscHMapIIterSet()`
285: M*/

287: /*MC
288:   PetscHMapIDel - Remove a key and its value from the hash table

290:   Synopsis:
291: #include <petsc/private/hashmapi.h>
292:   PetscErrorCode PetscHMapIDel(PetscHMapI ht,PetscInt key)

294:   Input Parameters:
295: + ht  - The hash table
296: - key - The key

298:   Level: developer

300: .seealso: `PetscHMapIHas()`, `PetscHMapIIterDel()`
301: M*/

303: /*MC
304:   PetscHMapIQuerySet - Query and set a (key,value) entry in the hash table

306:   Synopsis:
307: #include <petsc/private/hashmapi.h>
308:   PetscErrorCode PetscHMapIQuerySet(PetscHMapI ht, PetscInt key,  val, PetscBool *missing)

310:   Input Parameters:
311: + ht  - The hash table
312: . key - The key
313: - val - The value

315:   Output Parameter:
316: . missing - Boolean indicating whether the key was missing

318:   Level: developer

320: .seealso: `PetscHMapIQueryDel()`, `PetscHMapISet()`, `PetscHMapISetWithMode()`
321: M*/

323: /*MC
324:   PetscHMapIQueryDel - Query and remove a (key,value) entry from the hash table

326:   Synopsis:
327: #include <petsc/private/hashmapi.h>
328:   PetscErrorCode PetscHMapIQueryDel(PetscHMapI ht, PetscInt key, PetscBool *present)

330:   Input Parameters:
331: + ht  - The hash table
332: - key - The key

334:   Output Parameter:
335: . present - Boolean indicating whether the key was present

337:   Level: developer

339: .seealso: `PetscHMapIQuerySet()`, `PetscHMapIDel()`
340: M*/

342: /*MC
343:   PetscHMapIFind - Query for key in the hash table

345:   Synopsis:
346: #include <petsc/private/hashmapi.h>
347:   PetscErrorCode PetscHMapIFind(PetscHMapI ht, PetscInt key, PetscHashIter *iter, PetscBool *found)

349:   Input Parameters:
350: + ht  - The hash table
351: - key - The key

353:   Output Parameters:
354: + iter - Iterator referencing the value for key
355: - found - Boolean indicating whether the key was present

357:   Level: developer

359: .seealso: `PetscHMapIIterGet()`, `PetscHMapIIterDel()`
360: M*/

362: /*MC
363:   PetscHMapIPut - Set a key in the hash table

365:   Synopsis:
366: #include <petsc/private/hashmapi.h>
367:   PetscErrorCode PetscHMapIPut(PetscHMapI ht, PetscInt key, PetscHashIter *iter, PetscBool *missing)

369:   Input Parameters:
370: + ht  - The hash table
371: - key - The key

373:   Output Parameters:
374: + iter - Iterator referencing the value for key
375: - missing - Boolean indicating whether the key was missing

377:   Level: developer

379: .seealso: `PetscHMapIIterSet()`, `PetscHMapIQuerySet()`, `PetscHMapISet()`,
380: `PetscHMapISetWithMode()`
381: M*/

383: /*MC
384:   PetscHMapIIterGet - Get the value referenced by an iterator in the hash table

386:   Synopsis:
387: #include <petsc/private/hashmapi.h>
388:   PetscErrorCode PetscHMapIIterGet(PetscHMapI ht, PetscHashIter iter,  *val)

390:   Input Parameters:
391: + ht   - The hash table
392: - iter - The iterator

394:   Output Parameter:
395: . val  - The value

397:   Level: developer

399: .seealso: `PetscHMapIFind()`, `PetscHMapIGet()`, `PetscHMapIGetWithDefault()`
400: M*/

402: /*MC
403:   PetscHMapIIterSet - Set the value referenced by an iterator in the hash

405:   Synopsis:
406: #include <petsc/private/hashmapi.h>
407:   PetscErrorCode PetscHMapIIterSet(PetscHMapI ht, PetscHashIter iter,  val)

409:   Input Parameters:
410: + ht   - The hash table
411: . iter - The iterator
412: - val  - The value

414:   Level: developer

416: .seealso: `PetscHMapIPut()`, `PetscHMapIQuerySet()`, `PetscHMapISet()`,
417: `PetscHMapISetWithMode()`
418: M*/

420: /*MC
421:   PetscHMapIIterDel - Remove the (key,value) referenced by an iterator from the hash table

423:   Synopsis:
424: #include <petsc/private/hashmapi.h>
425:   PetscErrorCode PetscHMapIIterDel(PetscHMapI ht, PetscHashIter iter)

427:   Input Parameters:
428: + ht   - The hash table
429: - iter - The iterator

431:   Level: developer

433: .seealso: `PetscHMapIFind()`, `PetscHMapIQueryDel()`, `PetscHMapIDel()`
434: M*/

436: /*MC
437:   PetscHMapIGetKeys - Get all keys from a hash table

439:   Synopsis:
440: #include <petsc/private/hashmapi.h>
441:   PetscErrorCode PetscHMapIGetKeys(PetscHMapI ht, PetscInt *off, PetscInt array[])

443:   Input Parameters:
444: + ht    - The hash table
445: . off   - Input offset in array (usually zero)
446: - array - Array to put hash table keys in

448:   Output Parameters:
449: + off   - Output offset in array (output offset = input offset + hash table size)
450: - array - Array filled with the hash table keys

452:   Level: developer

454: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetVals()`
455: M*/

457: /*MC
458:   PetscHMapIGetVals - Get all values from a hash table

460:   Synopsis:
461: #include <petsc/private/hashmapi.h>
462:   PetscErrorCode PetscHMapIGetVals(PetscHMapI ht, PetscInt *off,  array[])

464:   Input Parameters:
465: + ht    - The hash table
466: . off   - Input offset in array (usually zero)
467: - array - Array to put hash table values in

469:   Output Parameters:
470: + off   - Output offset in array (output offset = input offset + hash table size)
471: - array - Array filled with the hash table values

473:   Level: developer

475: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetKeys()`
476: M*/

478: /*MC
479:   PetscHMapIGetPairs - Get all (key,value) pairs from a hash table

481:   Synopsis:
482: #include <petsc/private/hashmapi.h>
483:   PetscErrorCode PetscHMapIGetPairs(PetscHMapI ht, PetscInt *off, PetscInt karray[],  varray[])

485:   Input Parameters:
486: + ht    - The hash table
487: . off   - Input offset in array (usually zero)
488: . karray - Array to put hash table keys in
489: - varray - Array to put hash table values in

491:   Output Parameters:
492: + off   - Output offset in array (output offset = input offset + hash table size)
493: . karray - Array filled with the hash table keys
494: - varray - Array filled with the hash table values

496:   Level: developer

498: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetKeys()`, `PetscHMapIGetVals()`
499: M*/
500: /* SUBMANSEC = PetscH */

502: This file is processed by make allmanpages in $PETSC_DIR/makefile to create manual pages
503: for the types and macros created by PETSC_HASH_MAP(). For example, PetscHMAPIJ.

505: /*S
506:   PetscHMapIJ - Hash table map with a key of struct {PetscInt i, j;}

508:   Synopsis:
509:   typedef khash_t(HMapIJ) *PetscHMapIJ;

511:   Level: developer

513: .seealso: `PETSC_HASH_MAP()`, `PetscHMapIJCreate()`, `PETSC_HASH_SET()`, `PetscHSetIJCreate()`
514: S*/
515: typedef struct _PetscHashIJ PetscHMapIJ;

517: /*MC
518:   PetscHMapIJCreate - Create a hash table

520:   Synopsis:
521: #include <petsc/private/hashmapij.h>
522:   PetscErrorCode PetscHMapIJCreate(PetscHMapIJ *ht)

524:   Output Parameter:
525: . ht - The hash table

527:   Level: developer

529: .seealso: `PetscHMapIJCreateWithSize()`, `PetscHMapIJDestroy()`
530: M*/

532: /*MC
533:   PetscHMapIJCreateWithSize - Create a hash table with a given initial size

535:   Synopsis:
536: #include <petsc/private/hashmapij.h>
537:   PetscErrorCode PetscHMapIJCreateWithSize(PetscInt n, PetscHMapIJ *ht)

539:   Input Parameter:
540: . n - The size of the hash table

542:   Output Parameter:
543: . ht - The hash table

545:   Level: developer

547:   Note:
548:   `n` must be non-negative.

550: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJDestroy()`
551: M*/

553: /*MC
554:   PetscHMapIJDestroy - Destroy a hash table

556:   Synopsis:
557: #include <petsc/private/hashmapij.h>
558:   PetscErrorCode PetscHMapIJDestroy(PetscHMapIJ *ht)

560:   Input Parameter:
561: . ht - The hash table

563:   Level: developer

565: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJCreateWithSize()`
566: M*/

568: /*MC
569:   PetscHMapIJReset - Reset a hash table

571:   Synopsis:
572: #include <petsc/private/hashmapij.h>
573:   PetscErrorCode PetscHMapIJReset(PetscHMapIJ ht)

575:   Input Parameter:
576: . ht - The hash table

578:   Level: developer

580: .seealso: `PetscHMapIJClear()`
581: M*/

583: /*MC
584:   PetscHMapIJDuplicate - Duplicate a hash table

586:   Synopsis:
587: #include <petsc/private/hashmapij.h>
588:   PetscErrorCode PetscHMapIJDuplicate(PetscHMapIJ ht, PetscHMapIJ *hd)

590:   Input Parameter:
591: . ht - The source hash table

593:   Output Parameter:
594: . ht - The duplicated hash table

596:   Level: developer

598: .seealso: `PetscHMapIJCreate()`
599: M*/

601: /*MC
602:   PetscHMapIJClear - Clear a hash table

604:   Synopsis:
605: #include <petsc/private/hashmapij.h>
606:   PetscErrorCode PetscHMapIJClear(PetscHMapIJ ht)

608:   Input Parameter:
609: . ht - The hash table

611:   Level: developer

613: .seealso: `PetscHMapIJReset()`
614: M*/

616: /*MC
617:   PetscHMapIJResize - Set the number of buckets in a hash table

619:   Synopsis:
620: #include <petsc/private/hashmapij.h>
621:   PetscErrorCode PetscHMapIJResize(PetscHMapIJ ht, PetscInt nb)

623:   Input Parameters:
624: + ht - The hash table
625: - nb - The number of buckets

627:   Level: developer

629: .seealso: `PetscHMapIJCreate()`
630: M*/

632: /*MC
633:   PetscHMapIJGetSize - Get the number of entries in a hash table

635:   Synopsis:
636: #include <petsc/private/hashmapij.h>
637:   PetscErrorCode PetscHMapIJGetSize(PetscHMapIJ ht, PetscInt *n)

639:   Input Parameter:
640: . ht - The hash table

642:   Output Parameter:
643: . n - The number of entries

645:   Level: developer

647: .seealso: `PetscHMapIJResize()`
648: M*/

650: /*MC
651:   PetscHMapIJGetCapacity - Get the current size of the array in the hash table

653:   Synopsis:
654: #include <petsc/private/hashmapij.h>
655:   PetscErrorCode PetscHMapIJGetCapacity(PetscHMapIJ ht, PetscInt *n)

657:   Input Parameter:
658: . ht - The hash table

660:   Output Parameter:
661: . n - The capacity

663:   Level: developer

665: .seealso: `PetscHMapIJResize()`, `PetscHMapIJGetSize()`
666: M*/

668: /*MC
669:   PetscHMapIJHas - Query for a key in the hash table

671:   Synopsis:
672: #include <petsc/private/hashmapij.h>
673:   PetscErrorCode PetscHMapIJHas(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscBool *has)

675:   Input Parameters:
676: + ht  - The hash table
677: - key - The key

679:   Output Parameter:
680: . has - Boolean indicating whether key is in the hash table

682:   Level: developer

684: .seealso: `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`, `PetscHMapIJSet()`,
685: `PetscHMapIJSetWithMode()`, `PetscHMapIJFind()`
686: M*/

688: /*MC
689:   PetscHMapIJGet - Get the value for a key in the hash table

691:   Synopsis:
692: #include <petsc/private/hashmapij.h>
693:   PetscErrorCode PetscHMapIJGet(PetscHMapIJ ht, struct {PetscInt i, j;} key,  *val)

695:   Input Parameters:
696: + ht  - The hash table
697: - key - The key

699:   Output Parameter:
700: . val - The value

702:   Level: developer

704: .seealso: `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`,
705: `PetscHMapIJGetWithDefault()`
706: M*/

708: /*MC
709:   PetscHMapIJGetWithDefault - Get the value for a key in the hash table but override the default
710:   value returned if the key was not found

712:   Synopsis:
713: #include <petsc/private/hashmapij.h>
714:   PetscErrorCode PetscHMapIJGetWithDefault(PetscHMapIJ ht, struct {PetscInt i, j;} key,  default_val,  *val)

716:   Input Parameters:
717: + ht          - The hash table
718: . key         - The key
719: - default_val - The default value to set `val` to if `key` was not found

721:   Output Parameter:
722: . val - The value

724:   Level: developer

726: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`
727: M*/


730: /*MC
731:   PetscHMapIJSet - Set a (key,value) entry in the hash table

733:   Synopsis:
734: #include <petsc/private/hashmapij.h>
735:   PetscErrorCode PetscHMapIJSet(PetscHMapIJ ht, struct {PetscInt i, j;} key,  val)

737:   Input Parameters:
738: + ht  - The hash table
739: . key - The key
740: - val - The value

742:   Level: developer

744: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJGetWithDefault()`,
745: `PetscHMapIJIterSet()`
746: M*/

748: /*MC
749:   PetscHMapIJSetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode`

751:   Synopsis:
752: #include <petsc/private/hashmapij.h>
753:   PetscErrorCode PetscHMapIJSetWithMode(PetscHMapIJ ht, struct {PetscInt i, j;} key,  val, InsertMode mode)

755:   Input Parameters:
756: + ht   - The hash table
757: . key  - The key
758: . val  - The value
759: - mode - The insertion mode

761:   Level: developer

763:   Notes:
764:   `mode` may be any of the following\:
765:   - `INSERT_VALUES`\: this routine behaves identically to `PetscHMapIJSet()`.
766:   - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`)
767:                    is inserted into `ht` as-if-by `INSERT_VALUES`.
768:   - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the
769:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
770:                    `INSERT_VALUES`.
771:   - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the
772:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
773:                    `INSERT_VALUES`.

775:    All other `InsertMode` values raise an error.

777:    Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type
778:    it is not available by default for all PETSc hash table instantiations. If a particular
779:    instantiation supports this routine it must define `PETSC_HMAPIJ_HAVE_EXTENDED_API` to
780:    `1`.

782: .seealso: `PetscHMapIJSet()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`,
783: `PetscHMapIJIterSet()`
784: M*/

786: /*MC
787:   PetscHMapIJDel - Remove a key and its value from the hash table

789:   Synopsis:
790: #include <petsc/private/hashmapij.h>
791:   PetscErrorCode PetscHMapIJDel(PetscHMapIJ ht,struct {PetscInt i, j;} key)

793:   Input Parameters:
794: + ht  - The hash table
795: - key - The key

797:   Level: developer

799: .seealso: `PetscHMapIJHas()`, `PetscHMapIJIterDel()`
800: M*/

802: /*MC
803:   PetscHMapIJQuerySet - Query and set a (key,value) entry in the hash table

805:   Synopsis:
806: #include <petsc/private/hashmapij.h>
807:   PetscErrorCode PetscHMapIJQuerySet(PetscHMapIJ ht, struct {PetscInt i, j;} key,  val, PetscBool *missing)

809:   Input Parameters:
810: + ht  - The hash table
811: . key - The key
812: - val - The value

814:   Output Parameter:
815: . missing - Boolean indicating whether the key was missing

817:   Level: developer

819: .seealso: `PetscHMapIJQueryDel()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`
820: M*/

822: /*MC
823:   PetscHMapIJQueryDel - Query and remove a (key,value) entry from the hash table

825:   Synopsis:
826: #include <petsc/private/hashmapij.h>
827:   PetscErrorCode PetscHMapIJQueryDel(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscBool *present)

829:   Input Parameters:
830: + ht  - The hash table
831: - key - The key

833:   Output Parameter:
834: . present - Boolean indicating whether the key was present

836:   Level: developer

838: .seealso: `PetscHMapIJQuerySet()`, `PetscHMapIJDel()`
839: M*/

841: /*MC
842:   PetscHMapIJFind - Query for key in the hash table

844:   Synopsis:
845: #include <petsc/private/hashmapij.h>
846:   PetscErrorCode PetscHMapIJFind(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscHashIter *iter, PetscBool *found)

848:   Input Parameters:
849: + ht  - The hash table
850: - key - The key

852:   Output Parameters:
853: + iter - Iterator referencing the value for key
854: - found - Boolean indicating whether the key was present

856:   Level: developer

858: .seealso: `PetscHMapIJIterGet()`, `PetscHMapIJIterDel()`
859: M*/

861: /*MC
862:   PetscHMapIJPut - Set a key in the hash table

864:   Synopsis:
865: #include <petsc/private/hashmapij.h>
866:   PetscErrorCode PetscHMapIJPut(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscHashIter *iter, PetscBool *missing)

868:   Input Parameters:
869: + ht  - The hash table
870: - key - The key

872:   Output Parameters:
873: + iter - Iterator referencing the value for key
874: - missing - Boolean indicating whether the key was missing

876:   Level: developer

878: .seealso: `PetscHMapIJIterSet()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
879: `PetscHMapIJSetWithMode()`
880: M*/

882: /*MC
883:   PetscHMapIJIterGet - Get the value referenced by an iterator in the hash table

885:   Synopsis:
886: #include <petsc/private/hashmapij.h>
887:   PetscErrorCode PetscHMapIJIterGet(PetscHMapIJ ht, PetscHashIter iter,  *val)

889:   Input Parameters:
890: + ht   - The hash table
891: - iter - The iterator

893:   Output Parameter:
894: . val  - The value

896:   Level: developer

898: .seealso: `PetscHMapIJFind()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`
899: M*/

901: /*MC
902:   PetscHMapIJIterSet - Set the value referenced by an iterator in the hash

904:   Synopsis:
905: #include <petsc/private/hashmapij.h>
906:   PetscErrorCode PetscHMapIJIterSet(PetscHMapIJ ht, PetscHashIter iter,  val)

908:   Input Parameters:
909: + ht   - The hash table
910: . iter - The iterator
911: - val  - The value

913:   Level: developer

915: .seealso: `PetscHMapIJPut()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
916: `PetscHMapIJSetWithMode()`
917: M*/

919: /*MC
920:   PetscHMapIJIterDel - Remove the (key,value) referenced by an iterator from the hash table

922:   Synopsis:
923: #include <petsc/private/hashmapij.h>
924:   PetscErrorCode PetscHMapIJIterDel(PetscHMapIJ ht, PetscHashIter iter)

926:   Input Parameters:
927: + ht   - The hash table
928: - iter - The iterator

930:   Level: developer

932: .seealso: `PetscHMapIJFind()`, `PetscHMapIJQueryDel()`, `PetscHMapIJDel()`
933: M*/

935: /*MC
936:   PetscHMapIJGetKeys - Get all keys from a hash table

938:   Synopsis:
939: #include <petsc/private/hashmapij.h>
940:   PetscErrorCode PetscHMapIJGetKeys(PetscHMapIJ ht, PetscInt *off, struct {PetscInt i, j;} array[])

942:   Input Parameters:
943: + ht    - The hash table
944: . off   - Input offset in array (usually zero)
945: - array - Array to put hash table keys in

947:   Output Parameters:
948: + off   - Output offset in array (output offset = input offset + hash table size)
949: - array - Array filled with the hash table keys

951:   Level: developer

953: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetVals()`
954: M*/

956: /*MC
957:   PetscHMapIJGetVals - Get all values from a hash table

959:   Synopsis:
960: #include <petsc/private/hashmapij.h>
961:   PetscErrorCode PetscHMapIJGetVals(PetscHMapIJ ht, PetscInt *off,  array[])

963:   Input Parameters:
964: + ht    - The hash table
965: . off   - Input offset in array (usually zero)
966: - array - Array to put hash table values in

968:   Output Parameters:
969: + off   - Output offset in array (output offset = input offset + hash table size)
970: - array - Array filled with the hash table values

972:   Level: developer

974: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`
975: M*/

977: /*MC
978:   PetscHMapIJGetPairs - Get all (key,value) pairs from a hash table

980:   Synopsis:
981: #include <petsc/private/hashmapij.h>
982:   PetscErrorCode PetscHMapIJGetPairs(PetscHMapIJ ht, PetscInt *off, struct {PetscInt i, j;} karray[],  varray[])

984:   Input Parameters:
985: + ht    - The hash table
986: . off   - Input offset in array (usually zero)
987: . karray - Array to put hash table keys in
988: - varray - Array to put hash table values in

990:   Output Parameters:
991: + off   - Output offset in array (output offset = input offset + hash table size)
992: . karray - Array filled with the hash table keys
993: - varray - Array filled with the hash table values

995:   Level: developer

997: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`, `PetscHMapIJGetVals()`
998: M*/
999: /* SUBMANSEC = PetscH */

1001: This file is processed by make allmanpages in $PETSC_DIR/makefile to create manual pages
1002: for the types and macros created by PETSC_HASH_MAP(). For example, PetscHMAPIJ.

1004: /*S
1005:   PetscHMapI - Hash table map with a key of PetscInt

1007:   Synopsis:
1008:   typedef khash_t(HMapI) *PetscHMapI;

1010:   Level: developer

1012: .seealso: `PETSC_HASH_MAP()`, `PetscHMapICreate()`, `PETSC_HASH_SET()`, `PetscHSetICreate()`
1013: S*/
1014: typedef struct _PetscHashI PetscHMapI;

1016: /*MC
1017:   PetscHMapICreate - Create a hash table

1019:   Synopsis:
1020: #include <petsc/private/hashmapi.h>
1021:   PetscErrorCode PetscHMapICreate(PetscHMapI *ht)

1023:   Output Parameter:
1024: . ht - The hash table

1026:   Level: developer

1028: .seealso: `PetscHMapICreateWithSize()`, `PetscHMapIDestroy()`
1029: M*/

1031: /*MC
1032:   PetscHMapICreateWithSize - Create a hash table with a given initial size

1034:   Synopsis:
1035: #include <petsc/private/hashmapi.h>
1036:   PetscErrorCode PetscHMapICreateWithSize(PetscInt n, PetscHMapI *ht)

1038:   Input Parameter:
1039: . n - The size of the hash table

1041:   Output Parameter:
1042: . ht - The hash table

1044:   Level: developer

1046:   Note:
1047:   `n` must be non-negative.

1049: .seealso: `PetscHMapICreate()`, `PetscHMapIDestroy()`
1050: M*/

1052: /*MC
1053:   PetscHMapIDestroy - Destroy a hash table

1055:   Synopsis:
1056: #include <petsc/private/hashmapi.h>
1057:   PetscErrorCode PetscHMapIDestroy(PetscHMapI *ht)

1059:   Input Parameter:
1060: . ht - The hash table

1062:   Level: developer

1064: .seealso: `PetscHMapICreate()`, `PetscHMapICreateWithSize()`
1065: M*/

1067: /*MC
1068:   PetscHMapIReset - Reset a hash table

1070:   Synopsis:
1071: #include <petsc/private/hashmapi.h>
1072:   PetscErrorCode PetscHMapIReset(PetscHMapI ht)

1074:   Input Parameter:
1075: . ht - The hash table

1077:   Level: developer

1079: .seealso: `PetscHMapIClear()`
1080: M*/

1082: /*MC
1083:   PetscHMapIDuplicate - Duplicate a hash table

1085:   Synopsis:
1086: #include <petsc/private/hashmapi.h>
1087:   PetscErrorCode PetscHMapIDuplicate(PetscHMapI ht, PetscHMapI *hd)

1089:   Input Parameter:
1090: . ht - The source hash table

1092:   Output Parameter:
1093: . ht - The duplicated hash table

1095:   Level: developer

1097: .seealso: `PetscHMapICreate()`
1098: M*/

1100: /*MC
1101:   PetscHMapIClear - Clear a hash table

1103:   Synopsis:
1104: #include <petsc/private/hashmapi.h>
1105:   PetscErrorCode PetscHMapIClear(PetscHMapI ht)

1107:   Input Parameter:
1108: . ht - The hash table

1110:   Level: developer

1112: .seealso: `PetscHMapIReset()`
1113: M*/

1115: /*MC
1116:   PetscHMapIResize - Set the number of buckets in a hash table

1118:   Synopsis:
1119: #include <petsc/private/hashmapi.h>
1120:   PetscErrorCode PetscHMapIResize(PetscHMapI ht, PetscInt nb)

1122:   Input Parameters:
1123: + ht - The hash table
1124: - nb - The number of buckets

1126:   Level: developer

1128: .seealso: `PetscHMapICreate()`
1129: M*/

1131: /*MC
1132:   PetscHMapIGetSize - Get the number of entries in a hash table

1134:   Synopsis:
1135: #include <petsc/private/hashmapi.h>
1136:   PetscErrorCode PetscHMapIGetSize(PetscHMapI ht, PetscInt *n)

1138:   Input Parameter:
1139: . ht - The hash table

1141:   Output Parameter:
1142: . n - The number of entries

1144:   Level: developer

1146: .seealso: `PetscHMapIResize()`
1147: M*/

1149: /*MC
1150:   PetscHMapIGetCapacity - Get the current size of the array in the hash table

1152:   Synopsis:
1153: #include <petsc/private/hashmapi.h>
1154:   PetscErrorCode PetscHMapIGetCapacity(PetscHMapI ht, PetscInt *n)

1156:   Input Parameter:
1157: . ht - The hash table

1159:   Output Parameter:
1160: . n - The capacity

1162:   Level: developer

1164: .seealso: `PetscHMapIResize()`, `PetscHMapIGetSize()`
1165: M*/

1167: /*MC
1168:   PetscHMapIHas - Query for a key in the hash table

1170:   Synopsis:
1171: #include <petsc/private/hashmapi.h>
1172:   PetscErrorCode PetscHMapIHas(PetscHMapI ht, PetscInt key, PetscBool *has)

1174:   Input Parameters:
1175: + ht  - The hash table
1176: - key - The key

1178:   Output Parameter:
1179: . has - Boolean indicating whether key is in the hash table

1181:   Level: developer

1183: .seealso: `PetscHMapIGet()`, `PetscHMapIGetWithDefault()`, `PetscHMapISet()`,
1184: `PetscHMapISetWithMode()`, `PetscHMapIFind()`
1185: M*/

1187: /*MC
1188:   PetscHMapIGet - Get the value for a key in the hash table

1190:   Synopsis:
1191: #include <petsc/private/hashmapi.h>
1192:   PetscErrorCode PetscHMapIGet(PetscHMapI ht, PetscInt key, PetscInt *val)

1194:   Input Parameters:
1195: + ht  - The hash table
1196: - key - The key

1198:   Output Parameter:
1199: . val - The value

1201:   Level: developer

1203: .seealso: `PetscHMapISet()`, `PetscHMapISetWithMode()`, `PetscHMapIIterGet()`,
1204: `PetscHMapIGetWithDefault()`
1205: M*/

1207: /*MC
1208:   PetscHMapIGetWithDefault - Get the value for a key in the hash table but override the default
1209:   value returned if the key was not found

1211:   Synopsis:
1212: #include <petsc/private/hashmapi.h>
1213:   PetscErrorCode PetscHMapIGetWithDefault(PetscHMapI ht, PetscInt key, PetscInt default_val, PetscInt *val)

1215:   Input Parameters:
1216: + ht          - The hash table
1217: . key         - The key
1218: - default_val - The default value to set `val` to if `key` was not found

1220:   Output Parameter:
1221: . val - The value

1223:   Level: developer

1225: .seealso: `PetscHMapIGet()`, `PetscHMapISet()`, `PetscHMapISetWithMode()`, `PetscHMapIIterGet()`
1226: M*/


1229: /*MC
1230:   PetscHMapISet - Set a (key,value) entry in the hash table

1232:   Synopsis:
1233: #include <petsc/private/hashmapi.h>
1234:   PetscErrorCode PetscHMapISet(PetscHMapI ht, PetscInt key, PetscInt val)

1236:   Input Parameters:
1237: + ht  - The hash table
1238: . key - The key
1239: - val - The value

1241:   Level: developer

1243: .seealso: `PetscHMapIGet()`, `PetscHMapISetWithMode()`, `PetscHMapIGetWithDefault()`,
1244: `PetscHMapIIterSet()`
1245: M*/

1247: /*MC
1248:   PetscHMapISetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode`

1250:   Synopsis:
1251: #include <petsc/private/hashmapi.h>
1252:   PetscErrorCode PetscHMapISetWithMode(PetscHMapI ht, PetscInt key, PetscInt val, InsertMode mode)

1254:   Input Parameters:
1255: + ht   - The hash table
1256: . key  - The key
1257: . val  - The value
1258: - mode - The insertion mode

1260:   Level: developer

1262:   Notes:
1263:   `mode` may be any of the following\:
1264:   - `INSERT_VALUES`\: this routine behaves identically to `PetscHMapISet()`.
1265:   - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`)
1266:                    is inserted into `ht` as-if-by `INSERT_VALUES`.
1267:   - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the
1268:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
1269:                    `INSERT_VALUES`.
1270:   - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the
1271:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
1272:                    `INSERT_VALUES`.

1274:    All other `InsertMode` values raise an error.

1276:    Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type
1277:    it is not available by default for all PETSc hash table instantiations. If a particular
1278:    instantiation supports this routine it must define `PETSC_HMAPI_HAVE_EXTENDED_API` to
1279:    `1`.

1281: .seealso: `PetscHMapISet()`, `PetscHMapIGet()`, `PetscHMapIGetWithDefault()`,
1282: `PetscHMapIIterSet()`
1283: M*/

1285: /*MC
1286:   PetscHMapIDel - Remove a key and its value from the hash table

1288:   Synopsis:
1289: #include <petsc/private/hashmapi.h>
1290:   PetscErrorCode PetscHMapIDel(PetscHMapI ht,PetscInt key)

1292:   Input Parameters:
1293: + ht  - The hash table
1294: - key - The key

1296:   Level: developer

1298: .seealso: `PetscHMapIHas()`, `PetscHMapIIterDel()`
1299: M*/

1301: /*MC
1302:   PetscHMapIQuerySet - Query and set a (key,value) entry in the hash table

1304:   Synopsis:
1305: #include <petsc/private/hashmapi.h>
1306:   PetscErrorCode PetscHMapIQuerySet(PetscHMapI ht, PetscInt key, PetscInt val, PetscBool *missing)

1308:   Input Parameters:
1309: + ht  - The hash table
1310: . key - The key
1311: - val - The value

1313:   Output Parameter:
1314: . missing - Boolean indicating whether the key was missing

1316:   Level: developer

1318: .seealso: `PetscHMapIQueryDel()`, `PetscHMapISet()`, `PetscHMapISetWithMode()`
1319: M*/

1321: /*MC
1322:   PetscHMapIQueryDel - Query and remove a (key,value) entry from the hash table

1324:   Synopsis:
1325: #include <petsc/private/hashmapi.h>
1326:   PetscErrorCode PetscHMapIQueryDel(PetscHMapI ht, PetscInt key, PetscBool *present)

1328:   Input Parameters:
1329: + ht  - The hash table
1330: - key - The key

1332:   Output Parameter:
1333: . present - Boolean indicating whether the key was present

1335:   Level: developer

1337: .seealso: `PetscHMapIQuerySet()`, `PetscHMapIDel()`
1338: M*/

1340: /*MC
1341:   PetscHMapIFind - Query for key in the hash table

1343:   Synopsis:
1344: #include <petsc/private/hashmapi.h>
1345:   PetscErrorCode PetscHMapIFind(PetscHMapI ht, PetscInt key, PetscHashIter *iter, PetscBool *found)

1347:   Input Parameters:
1348: + ht  - The hash table
1349: - key - The key

1351:   Output Parameters:
1352: + iter - Iterator referencing the value for key
1353: - found - Boolean indicating whether the key was present

1355:   Level: developer

1357: .seealso: `PetscHMapIIterGet()`, `PetscHMapIIterDel()`
1358: M*/

1360: /*MC
1361:   PetscHMapIPut - Set a key in the hash table

1363:   Synopsis:
1364: #include <petsc/private/hashmapi.h>
1365:   PetscErrorCode PetscHMapIPut(PetscHMapI ht, PetscInt key, PetscHashIter *iter, PetscBool *missing)

1367:   Input Parameters:
1368: + ht  - The hash table
1369: - key - The key

1371:   Output Parameters:
1372: + iter - Iterator referencing the value for key
1373: - missing - Boolean indicating whether the key was missing

1375:   Level: developer

1377: .seealso: `PetscHMapIIterSet()`, `PetscHMapIQuerySet()`, `PetscHMapISet()`,
1378: `PetscHMapISetWithMode()`
1379: M*/

1381: /*MC
1382:   PetscHMapIIterGet - Get the value referenced by an iterator in the hash table

1384:   Synopsis:
1385: #include <petsc/private/hashmapi.h>
1386:   PetscErrorCode PetscHMapIIterGet(PetscHMapI ht, PetscHashIter iter, PetscInt *val)

1388:   Input Parameters:
1389: + ht   - The hash table
1390: - iter - The iterator

1392:   Output Parameter:
1393: . val  - The value

1395:   Level: developer

1397: .seealso: `PetscHMapIFind()`, `PetscHMapIGet()`, `PetscHMapIGetWithDefault()`
1398: M*/

1400: /*MC
1401:   PetscHMapIIterSet - Set the value referenced by an iterator in the hash

1403:   Synopsis:
1404: #include <petsc/private/hashmapi.h>
1405:   PetscErrorCode PetscHMapIIterSet(PetscHMapI ht, PetscHashIter iter, PetscInt val)

1407:   Input Parameters:
1408: + ht   - The hash table
1409: . iter - The iterator
1410: - val  - The value

1412:   Level: developer

1414: .seealso: `PetscHMapIPut()`, `PetscHMapIQuerySet()`, `PetscHMapISet()`,
1415: `PetscHMapISetWithMode()`
1416: M*/

1418: /*MC
1419:   PetscHMapIIterDel - Remove the (key,value) referenced by an iterator from the hash table

1421:   Synopsis:
1422: #include <petsc/private/hashmapi.h>
1423:   PetscErrorCode PetscHMapIIterDel(PetscHMapI ht, PetscHashIter iter)

1425:   Input Parameters:
1426: + ht   - The hash table
1427: - iter - The iterator

1429:   Level: developer

1431: .seealso: `PetscHMapIFind()`, `PetscHMapIQueryDel()`, `PetscHMapIDel()`
1432: M*/

1434: /*MC
1435:   PetscHMapIGetKeys - Get all keys from a hash table

1437:   Synopsis:
1438: #include <petsc/private/hashmapi.h>
1439:   PetscErrorCode PetscHMapIGetKeys(PetscHMapI ht, PetscInt *off, PetscInt array[])

1441:   Input Parameters:
1442: + ht    - The hash table
1443: . off   - Input offset in array (usually zero)
1444: - array - Array to put hash table keys in

1446:   Output Parameters:
1447: + off   - Output offset in array (output offset = input offset + hash table size)
1448: - array - Array filled with the hash table keys

1450:   Level: developer

1452: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetVals()`
1453: M*/

1455: /*MC
1456:   PetscHMapIGetVals - Get all values from a hash table

1458:   Synopsis:
1459: #include <petsc/private/hashmapi.h>
1460:   PetscErrorCode PetscHMapIGetVals(PetscHMapI ht, PetscInt *off, PetscInt array[])

1462:   Input Parameters:
1463: + ht    - The hash table
1464: . off   - Input offset in array (usually zero)
1465: - array - Array to put hash table values in

1467:   Output Parameters:
1468: + off   - Output offset in array (output offset = input offset + hash table size)
1469: - array - Array filled with the hash table values

1471:   Level: developer

1473: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetKeys()`
1474: M*/

1476: /*MC
1477:   PetscHMapIGetPairs - Get all (key,value) pairs from a hash table

1479:   Synopsis:
1480: #include <petsc/private/hashmapi.h>
1481:   PetscErrorCode PetscHMapIGetPairs(PetscHMapI ht, PetscInt *off, PetscInt karray[], PetscInt varray[])

1483:   Input Parameters:
1484: + ht    - The hash table
1485: . off   - Input offset in array (usually zero)
1486: . karray - Array to put hash table keys in
1487: - varray - Array to put hash table values in

1489:   Output Parameters:
1490: + off   - Output offset in array (output offset = input offset + hash table size)
1491: . karray - Array filled with the hash table keys
1492: - varray - Array filled with the hash table values

1494:   Level: developer

1496: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetKeys()`, `PetscHMapIGetVals()`
1497: M*/
1498: /* SUBMANSEC = PetscH */

1500: This file is processed by make allmanpages in $PETSC_DIR/makefile to create manual pages
1501: for the types and macros created by PETSC_HASH_MAP(). For example, PetscHMAPIJ.

1503: /*S
1504:   PetscHMapIJ - Hash table map with a key of struct {PetscInt i, j;}

1506:   Synopsis:
1507:   typedef khash_t(HMapIJ) *PetscHMapIJ;

1509:   Level: developer

1511: .seealso: `PETSC_HASH_MAP()`, `PetscHMapIJCreate()`, `PETSC_HASH_SET()`, `PetscHSetIJCreate()`
1512: S*/
1513: typedef struct _PetscHashIJ PetscHMapIJ;

1515: /*MC
1516:   PetscHMapIJCreate - Create a hash table

1518:   Synopsis:
1519: #include <petsc/private/hashmapij.h>
1520:   PetscErrorCode PetscHMapIJCreate(PetscHMapIJ *ht)

1522:   Output Parameter:
1523: . ht - The hash table

1525:   Level: developer

1527: .seealso: `PetscHMapIJCreateWithSize()`, `PetscHMapIJDestroy()`
1528: M*/

1530: /*MC
1531:   PetscHMapIJCreateWithSize - Create a hash table with a given initial size

1533:   Synopsis:
1534: #include <petsc/private/hashmapij.h>
1535:   PetscErrorCode PetscHMapIJCreateWithSize(PetscInt n, PetscHMapIJ *ht)

1537:   Input Parameter:
1538: . n - The size of the hash table

1540:   Output Parameter:
1541: . ht - The hash table

1543:   Level: developer

1545:   Note:
1546:   `n` must be non-negative.

1548: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJDestroy()`
1549: M*/

1551: /*MC
1552:   PetscHMapIJDestroy - Destroy a hash table

1554:   Synopsis:
1555: #include <petsc/private/hashmapij.h>
1556:   PetscErrorCode PetscHMapIJDestroy(PetscHMapIJ *ht)

1558:   Input Parameter:
1559: . ht - The hash table

1561:   Level: developer

1563: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJCreateWithSize()`
1564: M*/

1566: /*MC
1567:   PetscHMapIJReset - Reset a hash table

1569:   Synopsis:
1570: #include <petsc/private/hashmapij.h>
1571:   PetscErrorCode PetscHMapIJReset(PetscHMapIJ ht)

1573:   Input Parameter:
1574: . ht - The hash table

1576:   Level: developer

1578: .seealso: `PetscHMapIJClear()`
1579: M*/

1581: /*MC
1582:   PetscHMapIJDuplicate - Duplicate a hash table

1584:   Synopsis:
1585: #include <petsc/private/hashmapij.h>
1586:   PetscErrorCode PetscHMapIJDuplicate(PetscHMapIJ ht, PetscHMapIJ *hd)

1588:   Input Parameter:
1589: . ht - The source hash table

1591:   Output Parameter:
1592: . ht - The duplicated hash table

1594:   Level: developer

1596: .seealso: `PetscHMapIJCreate()`
1597: M*/

1599: /*MC
1600:   PetscHMapIJClear - Clear a hash table

1602:   Synopsis:
1603: #include <petsc/private/hashmapij.h>
1604:   PetscErrorCode PetscHMapIJClear(PetscHMapIJ ht)

1606:   Input Parameter:
1607: . ht - The hash table

1609:   Level: developer

1611: .seealso: `PetscHMapIJReset()`
1612: M*/

1614: /*MC
1615:   PetscHMapIJResize - Set the number of buckets in a hash table

1617:   Synopsis:
1618: #include <petsc/private/hashmapij.h>
1619:   PetscErrorCode PetscHMapIJResize(PetscHMapIJ ht, PetscInt nb)

1621:   Input Parameters:
1622: + ht - The hash table
1623: - nb - The number of buckets

1625:   Level: developer

1627: .seealso: `PetscHMapIJCreate()`
1628: M*/

1630: /*MC
1631:   PetscHMapIJGetSize - Get the number of entries in a hash table

1633:   Synopsis:
1634: #include <petsc/private/hashmapij.h>
1635:   PetscErrorCode PetscHMapIJGetSize(PetscHMapIJ ht, PetscInt *n)

1637:   Input Parameter:
1638: . ht - The hash table

1640:   Output Parameter:
1641: . n - The number of entries

1643:   Level: developer

1645: .seealso: `PetscHMapIJResize()`
1646: M*/

1648: /*MC
1649:   PetscHMapIJGetCapacity - Get the current size of the array in the hash table

1651:   Synopsis:
1652: #include <petsc/private/hashmapij.h>
1653:   PetscErrorCode PetscHMapIJGetCapacity(PetscHMapIJ ht, PetscInt *n)

1655:   Input Parameter:
1656: . ht - The hash table

1658:   Output Parameter:
1659: . n - The capacity

1661:   Level: developer

1663: .seealso: `PetscHMapIJResize()`, `PetscHMapIJGetSize()`
1664: M*/

1666: /*MC
1667:   PetscHMapIJHas - Query for a key in the hash table

1669:   Synopsis:
1670: #include <petsc/private/hashmapij.h>
1671:   PetscErrorCode PetscHMapIJHas(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscBool *has)

1673:   Input Parameters:
1674: + ht  - The hash table
1675: - key - The key

1677:   Output Parameter:
1678: . has - Boolean indicating whether key is in the hash table

1680:   Level: developer

1682: .seealso: `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`, `PetscHMapIJSet()`,
1683: `PetscHMapIJSetWithMode()`, `PetscHMapIJFind()`
1684: M*/

1686: /*MC
1687:   PetscHMapIJGet - Get the value for a key in the hash table

1689:   Synopsis:
1690: #include <petsc/private/hashmapij.h>
1691:   PetscErrorCode PetscHMapIJGet(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscInt *val)

1693:   Input Parameters:
1694: + ht  - The hash table
1695: - key - The key

1697:   Output Parameter:
1698: . val - The value

1700:   Level: developer

1702: .seealso: `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`,
1703: `PetscHMapIJGetWithDefault()`
1704: M*/

1706: /*MC
1707:   PetscHMapIJGetWithDefault - Get the value for a key in the hash table but override the default
1708:   value returned if the key was not found

1710:   Synopsis:
1711: #include <petsc/private/hashmapij.h>
1712:   PetscErrorCode PetscHMapIJGetWithDefault(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscInt default_val, PetscInt *val)

1714:   Input Parameters:
1715: + ht          - The hash table
1716: . key         - The key
1717: - default_val - The default value to set `val` to if `key` was not found

1719:   Output Parameter:
1720: . val - The value

1722:   Level: developer

1724: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`
1725: M*/


1728: /*MC
1729:   PetscHMapIJSet - Set a (key,value) entry in the hash table

1731:   Synopsis:
1732: #include <petsc/private/hashmapij.h>
1733:   PetscErrorCode PetscHMapIJSet(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscInt val)

1735:   Input Parameters:
1736: + ht  - The hash table
1737: . key - The key
1738: - val - The value

1740:   Level: developer

1742: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJGetWithDefault()`,
1743: `PetscHMapIJIterSet()`
1744: M*/

1746: /*MC
1747:   PetscHMapIJSetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode`

1749:   Synopsis:
1750: #include <petsc/private/hashmapij.h>
1751:   PetscErrorCode PetscHMapIJSetWithMode(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscInt val, InsertMode mode)

1753:   Input Parameters:
1754: + ht   - The hash table
1755: . key  - The key
1756: . val  - The value
1757: - mode - The insertion mode

1759:   Level: developer

1761:   Notes:
1762:   `mode` may be any of the following\:
1763:   - `INSERT_VALUES`\: this routine behaves identically to `PetscHMapIJSet()`.
1764:   - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`)
1765:                    is inserted into `ht` as-if-by `INSERT_VALUES`.
1766:   - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the
1767:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
1768:                    `INSERT_VALUES`.
1769:   - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the
1770:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
1771:                    `INSERT_VALUES`.

1773:    All other `InsertMode` values raise an error.

1775:    Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type
1776:    it is not available by default for all PETSc hash table instantiations. If a particular
1777:    instantiation supports this routine it must define `PETSC_HMAPIJ_HAVE_EXTENDED_API` to
1778:    `1`.

1780: .seealso: `PetscHMapIJSet()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`,
1781: `PetscHMapIJIterSet()`
1782: M*/

1784: /*MC
1785:   PetscHMapIJDel - Remove a key and its value from the hash table

1787:   Synopsis:
1788: #include <petsc/private/hashmapij.h>
1789:   PetscErrorCode PetscHMapIJDel(PetscHMapIJ ht,struct {PetscInt i, j;} key)

1791:   Input Parameters:
1792: + ht  - The hash table
1793: - key - The key

1795:   Level: developer

1797: .seealso: `PetscHMapIJHas()`, `PetscHMapIJIterDel()`
1798: M*/

1800: /*MC
1801:   PetscHMapIJQuerySet - Query and set a (key,value) entry in the hash table

1803:   Synopsis:
1804: #include <petsc/private/hashmapij.h>
1805:   PetscErrorCode PetscHMapIJQuerySet(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscInt val, PetscBool *missing)

1807:   Input Parameters:
1808: + ht  - The hash table
1809: . key - The key
1810: - val - The value

1812:   Output Parameter:
1813: . missing - Boolean indicating whether the key was missing

1815:   Level: developer

1817: .seealso: `PetscHMapIJQueryDel()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`
1818: M*/

1820: /*MC
1821:   PetscHMapIJQueryDel - Query and remove a (key,value) entry from the hash table

1823:   Synopsis:
1824: #include <petsc/private/hashmapij.h>
1825:   PetscErrorCode PetscHMapIJQueryDel(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscBool *present)

1827:   Input Parameters:
1828: + ht  - The hash table
1829: - key - The key

1831:   Output Parameter:
1832: . present - Boolean indicating whether the key was present

1834:   Level: developer

1836: .seealso: `PetscHMapIJQuerySet()`, `PetscHMapIJDel()`
1837: M*/

1839: /*MC
1840:   PetscHMapIJFind - Query for key in the hash table

1842:   Synopsis:
1843: #include <petsc/private/hashmapij.h>
1844:   PetscErrorCode PetscHMapIJFind(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscHashIter *iter, PetscBool *found)

1846:   Input Parameters:
1847: + ht  - The hash table
1848: - key - The key

1850:   Output Parameters:
1851: + iter - Iterator referencing the value for key
1852: - found - Boolean indicating whether the key was present

1854:   Level: developer

1856: .seealso: `PetscHMapIJIterGet()`, `PetscHMapIJIterDel()`
1857: M*/

1859: /*MC
1860:   PetscHMapIJPut - Set a key in the hash table

1862:   Synopsis:
1863: #include <petsc/private/hashmapij.h>
1864:   PetscErrorCode PetscHMapIJPut(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscHashIter *iter, PetscBool *missing)

1866:   Input Parameters:
1867: + ht  - The hash table
1868: - key - The key

1870:   Output Parameters:
1871: + iter - Iterator referencing the value for key
1872: - missing - Boolean indicating whether the key was missing

1874:   Level: developer

1876: .seealso: `PetscHMapIJIterSet()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
1877: `PetscHMapIJSetWithMode()`
1878: M*/

1880: /*MC
1881:   PetscHMapIJIterGet - Get the value referenced by an iterator in the hash table

1883:   Synopsis:
1884: #include <petsc/private/hashmapij.h>
1885:   PetscErrorCode PetscHMapIJIterGet(PetscHMapIJ ht, PetscHashIter iter, PetscInt *val)

1887:   Input Parameters:
1888: + ht   - The hash table
1889: - iter - The iterator

1891:   Output Parameter:
1892: . val  - The value

1894:   Level: developer

1896: .seealso: `PetscHMapIJFind()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`
1897: M*/

1899: /*MC
1900:   PetscHMapIJIterSet - Set the value referenced by an iterator in the hash

1902:   Synopsis:
1903: #include <petsc/private/hashmapij.h>
1904:   PetscErrorCode PetscHMapIJIterSet(PetscHMapIJ ht, PetscHashIter iter, PetscInt val)

1906:   Input Parameters:
1907: + ht   - The hash table
1908: . iter - The iterator
1909: - val  - The value

1911:   Level: developer

1913: .seealso: `PetscHMapIJPut()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
1914: `PetscHMapIJSetWithMode()`
1915: M*/

1917: /*MC
1918:   PetscHMapIJIterDel - Remove the (key,value) referenced by an iterator from the hash table

1920:   Synopsis:
1921: #include <petsc/private/hashmapij.h>
1922:   PetscErrorCode PetscHMapIJIterDel(PetscHMapIJ ht, PetscHashIter iter)

1924:   Input Parameters:
1925: + ht   - The hash table
1926: - iter - The iterator

1928:   Level: developer

1930: .seealso: `PetscHMapIJFind()`, `PetscHMapIJQueryDel()`, `PetscHMapIJDel()`
1931: M*/

1933: /*MC
1934:   PetscHMapIJGetKeys - Get all keys from a hash table

1936:   Synopsis:
1937: #include <petsc/private/hashmapij.h>
1938:   PetscErrorCode PetscHMapIJGetKeys(PetscHMapIJ ht, PetscInt *off, struct {PetscInt i, j;} array[])

1940:   Input Parameters:
1941: + ht    - The hash table
1942: . off   - Input offset in array (usually zero)
1943: - array - Array to put hash table keys in

1945:   Output Parameters:
1946: + off   - Output offset in array (output offset = input offset + hash table size)
1947: - array - Array filled with the hash table keys

1949:   Level: developer

1951: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetVals()`
1952: M*/

1954: /*MC
1955:   PetscHMapIJGetVals - Get all values from a hash table

1957:   Synopsis:
1958: #include <petsc/private/hashmapij.h>
1959:   PetscErrorCode PetscHMapIJGetVals(PetscHMapIJ ht, PetscInt *off, PetscInt array[])

1961:   Input Parameters:
1962: + ht    - The hash table
1963: . off   - Input offset in array (usually zero)
1964: - array - Array to put hash table values in

1966:   Output Parameters:
1967: + off   - Output offset in array (output offset = input offset + hash table size)
1968: - array - Array filled with the hash table values

1970:   Level: developer

1972: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`
1973: M*/

1975: /*MC
1976:   PetscHMapIJGetPairs - Get all (key,value) pairs from a hash table

1978:   Synopsis:
1979: #include <petsc/private/hashmapij.h>
1980:   PetscErrorCode PetscHMapIJGetPairs(PetscHMapIJ ht, PetscInt *off, struct {PetscInt i, j;} karray[], PetscInt varray[])

1982:   Input Parameters:
1983: + ht    - The hash table
1984: . off   - Input offset in array (usually zero)
1985: . karray - Array to put hash table keys in
1986: - varray - Array to put hash table values in

1988:   Output Parameters:
1989: + off   - Output offset in array (output offset = input offset + hash table size)
1990: . karray - Array filled with the hash table keys
1991: - varray - Array filled with the hash table values

1993:   Level: developer

1995: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`, `PetscHMapIJGetVals()`
1996: M*/
1997: /* SUBMANSEC = PetscH */

1999: This file is processed by make allmanpages in $PETSC_DIR/makefile to create manual pages
2000: for the types and macros created by PETSC_HASH_MAP(). For example, PetscHMAPIJ.

2002: /*S
2003:   PetscHMapIJ - Hash table map with a key of struct {PetscInt i, j;}

2005:   Synopsis:
2006:   typedef khash_t(HMapIJ) *PetscHMapIJ;

2008:   Level: developer

2010: .seealso: `PETSC_HASH_MAP()`, `PetscHMapIJCreate()`, `PETSC_HASH_SET()`, `PetscHSetIJCreate()`
2011: S*/
2012: typedef struct _PetscHashIJ PetscHMapIJ;

2014: /*MC
2015:   PetscHMapIJCreate - Create a hash table

2017:   Synopsis:
2018: #include <petsc/private/hashmapij.h>
2019:   PetscErrorCode PetscHMapIJCreate(PetscHMapIJ *ht)

2021:   Output Parameter:
2022: . ht - The hash table

2024:   Level: developer

2026: .seealso: `PetscHMapIJCreateWithSize()`, `PetscHMapIJDestroy()`
2027: M*/

2029: /*MC
2030:   PetscHMapIJCreateWithSize - Create a hash table with a given initial size

2032:   Synopsis:
2033: #include <petsc/private/hashmapij.h>
2034:   PetscErrorCode PetscHMapIJCreateWithSize(PetscInt n, PetscHMapIJ *ht)

2036:   Input Parameter:
2037: . n - The size of the hash table

2039:   Output Parameter:
2040: . ht - The hash table

2042:   Level: developer

2044:   Note:
2045:   `n` must be non-negative.

2047: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJDestroy()`
2048: M*/

2050: /*MC
2051:   PetscHMapIJDestroy - Destroy a hash table

2053:   Synopsis:
2054: #include <petsc/private/hashmapij.h>
2055:   PetscErrorCode PetscHMapIJDestroy(PetscHMapIJ *ht)

2057:   Input Parameter:
2058: . ht - The hash table

2060:   Level: developer

2062: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJCreateWithSize()`
2063: M*/

2065: /*MC
2066:   PetscHMapIJReset - Reset a hash table

2068:   Synopsis:
2069: #include <petsc/private/hashmapij.h>
2070:   PetscErrorCode PetscHMapIJReset(PetscHMapIJ ht)

2072:   Input Parameter:
2073: . ht - The hash table

2075:   Level: developer

2077: .seealso: `PetscHMapIJClear()`
2078: M*/

2080: /*MC
2081:   PetscHMapIJDuplicate - Duplicate a hash table

2083:   Synopsis:
2084: #include <petsc/private/hashmapij.h>
2085:   PetscErrorCode PetscHMapIJDuplicate(PetscHMapIJ ht, PetscHMapIJ *hd)

2087:   Input Parameter:
2088: . ht - The source hash table

2090:   Output Parameter:
2091: . ht - The duplicated hash table

2093:   Level: developer

2095: .seealso: `PetscHMapIJCreate()`
2096: M*/

2098: /*MC
2099:   PetscHMapIJClear - Clear a hash table

2101:   Synopsis:
2102: #include <petsc/private/hashmapij.h>
2103:   PetscErrorCode PetscHMapIJClear(PetscHMapIJ ht)

2105:   Input Parameter:
2106: . ht - The hash table

2108:   Level: developer

2110: .seealso: `PetscHMapIJReset()`
2111: M*/

2113: /*MC
2114:   PetscHMapIJResize - Set the number of buckets in a hash table

2116:   Synopsis:
2117: #include <petsc/private/hashmapij.h>
2118:   PetscErrorCode PetscHMapIJResize(PetscHMapIJ ht, PetscInt nb)

2120:   Input Parameters:
2121: + ht - The hash table
2122: - nb - The number of buckets

2124:   Level: developer

2126: .seealso: `PetscHMapIJCreate()`
2127: M*/

2129: /*MC
2130:   PetscHMapIJGetSize - Get the number of entries in a hash table

2132:   Synopsis:
2133: #include <petsc/private/hashmapij.h>
2134:   PetscErrorCode PetscHMapIJGetSize(PetscHMapIJ ht, PetscInt *n)

2136:   Input Parameter:
2137: . ht - The hash table

2139:   Output Parameter:
2140: . n - The number of entries

2142:   Level: developer

2144: .seealso: `PetscHMapIJResize()`
2145: M*/

2147: /*MC
2148:   PetscHMapIJGetCapacity - Get the current size of the array in the hash table

2150:   Synopsis:
2151: #include <petsc/private/hashmapij.h>
2152:   PetscErrorCode PetscHMapIJGetCapacity(PetscHMapIJ ht, PetscInt *n)

2154:   Input Parameter:
2155: . ht - The hash table

2157:   Output Parameter:
2158: . n - The capacity

2160:   Level: developer

2162: .seealso: `PetscHMapIJResize()`, `PetscHMapIJGetSize()`
2163: M*/

2165: /*MC
2166:   PetscHMapIJHas - Query for a key in the hash table

2168:   Synopsis:
2169: #include <petsc/private/hashmapij.h>
2170:   PetscErrorCode PetscHMapIJHas(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscBool *has)

2172:   Input Parameters:
2173: + ht  - The hash table
2174: - key - The key

2176:   Output Parameter:
2177: . has - Boolean indicating whether key is in the hash table

2179:   Level: developer

2181: .seealso: `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`, `PetscHMapIJSet()`,
2182: `PetscHMapIJSetWithMode()`, `PetscHMapIJFind()`
2183: M*/

2185: /*MC
2186:   PetscHMapIJGet - Get the value for a key in the hash table

2188:   Synopsis:
2189: #include <petsc/private/hashmapij.h>
2190:   PetscErrorCode PetscHMapIJGet(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscScalar *val)

2192:   Input Parameters:
2193: + ht  - The hash table
2194: - key - The key

2196:   Output Parameter:
2197: . val - The value

2199:   Level: developer

2201: .seealso: `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`,
2202: `PetscHMapIJGetWithDefault()`
2203: M*/

2205: /*MC
2206:   PetscHMapIJGetWithDefault - Get the value for a key in the hash table but override the default
2207:   value returned if the key was not found

2209:   Synopsis:
2210: #include <petsc/private/hashmapij.h>
2211:   PetscErrorCode PetscHMapIJGetWithDefault(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscScalar default_val, PetscScalar *val)

2213:   Input Parameters:
2214: + ht          - The hash table
2215: . key         - The key
2216: - default_val - The default value to set `val` to if `key` was not found

2218:   Output Parameter:
2219: . val - The value

2221:   Level: developer

2223: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`
2224: M*/


2227: /*MC
2228:   PetscHMapIJSet - Set a (key,value) entry in the hash table

2230:   Synopsis:
2231: #include <petsc/private/hashmapij.h>
2232:   PetscErrorCode PetscHMapIJSet(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscScalar val)

2234:   Input Parameters:
2235: + ht  - The hash table
2236: . key - The key
2237: - val - The value

2239:   Level: developer

2241: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJGetWithDefault()`,
2242: `PetscHMapIJIterSet()`
2243: M*/

2245: /*MC
2246:   PetscHMapIJSetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode`

2248:   Synopsis:
2249: #include <petsc/private/hashmapij.h>
2250:   PetscErrorCode PetscHMapIJSetWithMode(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscScalar val, InsertMode mode)

2252:   Input Parameters:
2253: + ht   - The hash table
2254: . key  - The key
2255: . val  - The value
2256: - mode - The insertion mode

2258:   Level: developer

2260:   Notes:
2261:   `mode` may be any of the following\:
2262:   - `INSERT_VALUES`\: this routine behaves identically to `PetscHMapIJSet()`.
2263:   - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`)
2264:                    is inserted into `ht` as-if-by `INSERT_VALUES`.
2265:   - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the
2266:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
2267:                    `INSERT_VALUES`.
2268:   - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the
2269:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
2270:                    `INSERT_VALUES`.

2272:    All other `InsertMode` values raise an error.

2274:    Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type
2275:    it is not available by default for all PETSc hash table instantiations. If a particular
2276:    instantiation supports this routine it must define `PETSC_HMAPIJ_HAVE_EXTENDED_API` to
2277:    `1`.

2279: .seealso: `PetscHMapIJSet()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`,
2280: `PetscHMapIJIterSet()`
2281: M*/

2283: /*MC
2284:   PetscHMapIJDel - Remove a key and its value from the hash table

2286:   Synopsis:
2287: #include <petsc/private/hashmapij.h>
2288:   PetscErrorCode PetscHMapIJDel(PetscHMapIJ ht,struct {PetscInt i, j;} key)

2290:   Input Parameters:
2291: + ht  - The hash table
2292: - key - The key

2294:   Level: developer

2296: .seealso: `PetscHMapIJHas()`, `PetscHMapIJIterDel()`
2297: M*/

2299: /*MC
2300:   PetscHMapIJQuerySet - Query and set a (key,value) entry in the hash table

2302:   Synopsis:
2303: #include <petsc/private/hashmapij.h>
2304:   PetscErrorCode PetscHMapIJQuerySet(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscScalar val, PetscBool *missing)

2306:   Input Parameters:
2307: + ht  - The hash table
2308: . key - The key
2309: - val - The value

2311:   Output Parameter:
2312: . missing - Boolean indicating whether the key was missing

2314:   Level: developer

2316: .seealso: `PetscHMapIJQueryDel()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`
2317: M*/

2319: /*MC
2320:   PetscHMapIJQueryDel - Query and remove a (key,value) entry from the hash table

2322:   Synopsis:
2323: #include <petsc/private/hashmapij.h>
2324:   PetscErrorCode PetscHMapIJQueryDel(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscBool *present)

2326:   Input Parameters:
2327: + ht  - The hash table
2328: - key - The key

2330:   Output Parameter:
2331: . present - Boolean indicating whether the key was present

2333:   Level: developer

2335: .seealso: `PetscHMapIJQuerySet()`, `PetscHMapIJDel()`
2336: M*/

2338: /*MC
2339:   PetscHMapIJFind - Query for key in the hash table

2341:   Synopsis:
2342: #include <petsc/private/hashmapij.h>
2343:   PetscErrorCode PetscHMapIJFind(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscHashIter *iter, PetscBool *found)

2345:   Input Parameters:
2346: + ht  - The hash table
2347: - key - The key

2349:   Output Parameters:
2350: + iter - Iterator referencing the value for key
2351: - found - Boolean indicating whether the key was present

2353:   Level: developer

2355: .seealso: `PetscHMapIJIterGet()`, `PetscHMapIJIterDel()`
2356: M*/

2358: /*MC
2359:   PetscHMapIJPut - Set a key in the hash table

2361:   Synopsis:
2362: #include <petsc/private/hashmapij.h>
2363:   PetscErrorCode PetscHMapIJPut(PetscHMapIJ ht, struct {PetscInt i, j;} key, PetscHashIter *iter, PetscBool *missing)

2365:   Input Parameters:
2366: + ht  - The hash table
2367: - key - The key

2369:   Output Parameters:
2370: + iter - Iterator referencing the value for key
2371: - missing - Boolean indicating whether the key was missing

2373:   Level: developer

2375: .seealso: `PetscHMapIJIterSet()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
2376: `PetscHMapIJSetWithMode()`
2377: M*/

2379: /*MC
2380:   PetscHMapIJIterGet - Get the value referenced by an iterator in the hash table

2382:   Synopsis:
2383: #include <petsc/private/hashmapij.h>
2384:   PetscErrorCode PetscHMapIJIterGet(PetscHMapIJ ht, PetscHashIter iter, PetscScalar *val)

2386:   Input Parameters:
2387: + ht   - The hash table
2388: - iter - The iterator

2390:   Output Parameter:
2391: . val  - The value

2393:   Level: developer

2395: .seealso: `PetscHMapIJFind()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`
2396: M*/

2398: /*MC
2399:   PetscHMapIJIterSet - Set the value referenced by an iterator in the hash

2401:   Synopsis:
2402: #include <petsc/private/hashmapij.h>
2403:   PetscErrorCode PetscHMapIJIterSet(PetscHMapIJ ht, PetscHashIter iter, PetscScalar val)

2405:   Input Parameters:
2406: + ht   - The hash table
2407: . iter - The iterator
2408: - val  - The value

2410:   Level: developer

2412: .seealso: `PetscHMapIJPut()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
2413: `PetscHMapIJSetWithMode()`
2414: M*/

2416: /*MC
2417:   PetscHMapIJIterDel - Remove the (key,value) referenced by an iterator from the hash table

2419:   Synopsis:
2420: #include <petsc/private/hashmapij.h>
2421:   PetscErrorCode PetscHMapIJIterDel(PetscHMapIJ ht, PetscHashIter iter)

2423:   Input Parameters:
2424: + ht   - The hash table
2425: - iter - The iterator

2427:   Level: developer

2429: .seealso: `PetscHMapIJFind()`, `PetscHMapIJQueryDel()`, `PetscHMapIJDel()`
2430: M*/

2432: /*MC
2433:   PetscHMapIJGetKeys - Get all keys from a hash table

2435:   Synopsis:
2436: #include <petsc/private/hashmapij.h>
2437:   PetscErrorCode PetscHMapIJGetKeys(PetscHMapIJ ht, PetscInt *off, struct {PetscInt i, j;} array[])

2439:   Input Parameters:
2440: + ht    - The hash table
2441: . off   - Input offset in array (usually zero)
2442: - array - Array to put hash table keys in

2444:   Output Parameters:
2445: + off   - Output offset in array (output offset = input offset + hash table size)
2446: - array - Array filled with the hash table keys

2448:   Level: developer

2450: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetVals()`
2451: M*/

2453: /*MC
2454:   PetscHMapIJGetVals - Get all values from a hash table

2456:   Synopsis:
2457: #include <petsc/private/hashmapij.h>
2458:   PetscErrorCode PetscHMapIJGetVals(PetscHMapIJ ht, PetscInt *off, PetscScalar array[])

2460:   Input Parameters:
2461: + ht    - The hash table
2462: . off   - Input offset in array (usually zero)
2463: - array - Array to put hash table values in

2465:   Output Parameters:
2466: + off   - Output offset in array (output offset = input offset + hash table size)
2467: - array - Array filled with the hash table values

2469:   Level: developer

2471: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`
2472: M*/

2474: /*MC
2475:   PetscHMapIJGetPairs - Get all (key,value) pairs from a hash table

2477:   Synopsis:
2478: #include <petsc/private/hashmapij.h>
2479:   PetscErrorCode PetscHMapIJGetPairs(PetscHMapIJ ht, PetscInt *off, struct {PetscInt i, j;} karray[], PetscScalar varray[])

2481:   Input Parameters:
2482: + ht    - The hash table
2483: . off   - Input offset in array (usually zero)
2484: . karray - Array to put hash table keys in
2485: - varray - Array to put hash table values in

2487:   Output Parameters:
2488: + off   - Output offset in array (output offset = input offset + hash table size)
2489: . karray - Array filled with the hash table keys
2490: - varray - Array filled with the hash table values

2492:   Level: developer

2494: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`, `PetscHMapIJGetVals()`
2495: M*/
2496: /* SUBMANSEC = PetscH */

2498: This file is processed by make allmanpages in $PETSC_DIR/makefile to create manual pages
2499: for the types and macros created by PETSC_HASH_MAP(). For example, PetscHMAPIJ.

2501: /*S
2502:   PetscHMapIV - Hash table map with a key of PetscInt

2504:   Synopsis:
2505:   typedef khash_t(HMapIV) *PetscHMapIV;

2507:   Level: developer

2509: .seealso: `PETSC_HASH_MAP()`, `PetscHMapIVCreate()`, `PETSC_HASH_SET()`, `PetscHSetIVCreate()`
2510: S*/
2511: typedef struct _PetscHashIV PetscHMapIV;

2513: /*MC
2514:   PetscHMapIVCreate - Create a hash table

2516:   Synopsis:
2517: #include <petsc/private/hashmapiv.h>
2518:   PetscErrorCode PetscHMapIVCreate(PetscHMapIV *ht)

2520:   Output Parameter:
2521: . ht - The hash table

2523:   Level: developer

2525: .seealso: `PetscHMapIVCreateWithSize()`, `PetscHMapIVDestroy()`
2526: M*/

2528: /*MC
2529:   PetscHMapIVCreateWithSize - Create a hash table with a given initial size

2531:   Synopsis:
2532: #include <petsc/private/hashmapiv.h>
2533:   PetscErrorCode PetscHMapIVCreateWithSize(PetscInt n, PetscHMapIV *ht)

2535:   Input Parameter:
2536: . n - The size of the hash table

2538:   Output Parameter:
2539: . ht - The hash table

2541:   Level: developer

2543:   Note:
2544:   `n` must be non-negative.

2546: .seealso: `PetscHMapIVCreate()`, `PetscHMapIVDestroy()`
2547: M*/

2549: /*MC
2550:   PetscHMapIVDestroy - Destroy a hash table

2552:   Synopsis:
2553: #include <petsc/private/hashmapiv.h>
2554:   PetscErrorCode PetscHMapIVDestroy(PetscHMapIV *ht)

2556:   Input Parameter:
2557: . ht - The hash table

2559:   Level: developer

2561: .seealso: `PetscHMapIVCreate()`, `PetscHMapIVCreateWithSize()`
2562: M*/

2564: /*MC
2565:   PetscHMapIVReset - Reset a hash table

2567:   Synopsis:
2568: #include <petsc/private/hashmapiv.h>
2569:   PetscErrorCode PetscHMapIVReset(PetscHMapIV ht)

2571:   Input Parameter:
2572: . ht - The hash table

2574:   Level: developer

2576: .seealso: `PetscHMapIVClear()`
2577: M*/

2579: /*MC
2580:   PetscHMapIVDuplicate - Duplicate a hash table

2582:   Synopsis:
2583: #include <petsc/private/hashmapiv.h>
2584:   PetscErrorCode PetscHMapIVDuplicate(PetscHMapIV ht, PetscHMapIV *hd)

2586:   Input Parameter:
2587: . ht - The source hash table

2589:   Output Parameter:
2590: . ht - The duplicated hash table

2592:   Level: developer

2594: .seealso: `PetscHMapIVCreate()`
2595: M*/

2597: /*MC
2598:   PetscHMapIVClear - Clear a hash table

2600:   Synopsis:
2601: #include <petsc/private/hashmapiv.h>
2602:   PetscErrorCode PetscHMapIVClear(PetscHMapIV ht)

2604:   Input Parameter:
2605: . ht - The hash table

2607:   Level: developer

2609: .seealso: `PetscHMapIVReset()`
2610: M*/

2612: /*MC
2613:   PetscHMapIVResize - Set the number of buckets in a hash table

2615:   Synopsis:
2616: #include <petsc/private/hashmapiv.h>
2617:   PetscErrorCode PetscHMapIVResize(PetscHMapIV ht, PetscInt nb)

2619:   Input Parameters:
2620: + ht - The hash table
2621: - nb - The number of buckets

2623:   Level: developer

2625: .seealso: `PetscHMapIVCreate()`
2626: M*/

2628: /*MC
2629:   PetscHMapIVGetSize - Get the number of entries in a hash table

2631:   Synopsis:
2632: #include <petsc/private/hashmapiv.h>
2633:   PetscErrorCode PetscHMapIVGetSize(PetscHMapIV ht, PetscInt *n)

2635:   Input Parameter:
2636: . ht - The hash table

2638:   Output Parameter:
2639: . n - The number of entries

2641:   Level: developer

2643: .seealso: `PetscHMapIVResize()`
2644: M*/

2646: /*MC
2647:   PetscHMapIVGetCapacity - Get the current size of the array in the hash table

2649:   Synopsis:
2650: #include <petsc/private/hashmapiv.h>
2651:   PetscErrorCode PetscHMapIVGetCapacity(PetscHMapIV ht, PetscInt *n)

2653:   Input Parameter:
2654: . ht - The hash table

2656:   Output Parameter:
2657: . n - The capacity

2659:   Level: developer

2661: .seealso: `PetscHMapIVResize()`, `PetscHMapIVGetSize()`
2662: M*/

2664: /*MC
2665:   PetscHMapIVHas - Query for a key in the hash table

2667:   Synopsis:
2668: #include <petsc/private/hashmapiv.h>
2669:   PetscErrorCode PetscHMapIVHas(PetscHMapIV ht, PetscInt key, PetscBool *has)

2671:   Input Parameters:
2672: + ht  - The hash table
2673: - key - The key

2675:   Output Parameter:
2676: . has - Boolean indicating whether key is in the hash table

2678:   Level: developer

2680: .seealso: `PetscHMapIVGet()`, `PetscHMapIVGetWithDefault()`, `PetscHMapIVSet()`,
2681: `PetscHMapIVSetWithMode()`, `PetscHMapIVFind()`
2682: M*/

2684: /*MC
2685:   PetscHMapIVGet - Get the value for a key in the hash table

2687:   Synopsis:
2688: #include <petsc/private/hashmapiv.h>
2689:   PetscErrorCode PetscHMapIVGet(PetscHMapIV ht, PetscInt key, PetscScalar *val)

2691:   Input Parameters:
2692: + ht  - The hash table
2693: - key - The key

2695:   Output Parameter:
2696: . val - The value

2698:   Level: developer

2700: .seealso: `PetscHMapIVSet()`, `PetscHMapIVSetWithMode()`, `PetscHMapIVIterGet()`,
2701: `PetscHMapIVGetWithDefault()`
2702: M*/

2704: /*MC
2705:   PetscHMapIVGetWithDefault - Get the value for a key in the hash table but override the default
2706:   value returned if the key was not found

2708:   Synopsis:
2709: #include <petsc/private/hashmapiv.h>
2710:   PetscErrorCode PetscHMapIVGetWithDefault(PetscHMapIV ht, PetscInt key, PetscScalar default_val, PetscScalar *val)

2712:   Input Parameters:
2713: + ht          - The hash table
2714: . key         - The key
2715: - default_val - The default value to set `val` to if `key` was not found

2717:   Output Parameter:
2718: . val - The value

2720:   Level: developer

2722: .seealso: `PetscHMapIVGet()`, `PetscHMapIVSet()`, `PetscHMapIVSetWithMode()`, `PetscHMapIVIterGet()`
2723: M*/


2726: /*MC
2727:   PetscHMapIVSet - Set a (key,value) entry in the hash table

2729:   Synopsis:
2730: #include <petsc/private/hashmapiv.h>
2731:   PetscErrorCode PetscHMapIVSet(PetscHMapIV ht, PetscInt key, PetscScalar val)

2733:   Input Parameters:
2734: + ht  - The hash table
2735: . key - The key
2736: - val - The value

2738:   Level: developer

2740: .seealso: `PetscHMapIVGet()`, `PetscHMapIVSetWithMode()`, `PetscHMapIVGetWithDefault()`,
2741: `PetscHMapIVIterSet()`
2742: M*/

2744: /*MC
2745:   PetscHMapIVSetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode`

2747:   Synopsis:
2748: #include <petsc/private/hashmapiv.h>
2749:   PetscErrorCode PetscHMapIVSetWithMode(PetscHMapIV ht, PetscInt key, PetscScalar val, InsertMode mode)

2751:   Input Parameters:
2752: + ht   - The hash table
2753: . key  - The key
2754: . val  - The value
2755: - mode - The insertion mode

2757:   Level: developer

2759:   Notes:
2760:   `mode` may be any of the following\:
2761:   - `INSERT_VALUES`\: this routine behaves identically to `PetscHMapIVSet()`.
2762:   - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`)
2763:                    is inserted into `ht` as-if-by `INSERT_VALUES`.
2764:   - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the
2765:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
2766:                    `INSERT_VALUES`.
2767:   - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the
2768:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
2769:                    `INSERT_VALUES`.

2771:    All other `InsertMode` values raise an error.

2773:    Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type
2774:    it is not available by default for all PETSc hash table instantiations. If a particular
2775:    instantiation supports this routine it must define `PETSC_HMAPIV_HAVE_EXTENDED_API` to
2776:    `1`.

2778: .seealso: `PetscHMapIVSet()`, `PetscHMapIVGet()`, `PetscHMapIVGetWithDefault()`,
2779: `PetscHMapIVIterSet()`
2780: M*/

2782: /*MC
2783:   PetscHMapIVDel - Remove a key and its value from the hash table

2785:   Synopsis:
2786: #include <petsc/private/hashmapiv.h>
2787:   PetscErrorCode PetscHMapIVDel(PetscHMapIV ht,PetscInt key)

2789:   Input Parameters:
2790: + ht  - The hash table
2791: - key - The key

2793:   Level: developer

2795: .seealso: `PetscHMapIVHas()`, `PetscHMapIVIterDel()`
2796: M*/

2798: /*MC
2799:   PetscHMapIVQuerySet - Query and set a (key,value) entry in the hash table

2801:   Synopsis:
2802: #include <petsc/private/hashmapiv.h>
2803:   PetscErrorCode PetscHMapIVQuerySet(PetscHMapIV ht, PetscInt key, PetscScalar val, PetscBool *missing)

2805:   Input Parameters:
2806: + ht  - The hash table
2807: . key - The key
2808: - val - The value

2810:   Output Parameter:
2811: . missing - Boolean indicating whether the key was missing

2813:   Level: developer

2815: .seealso: `PetscHMapIVQueryDel()`, `PetscHMapIVSet()`, `PetscHMapIVSetWithMode()`
2816: M*/

2818: /*MC
2819:   PetscHMapIVQueryDel - Query and remove a (key,value) entry from the hash table

2821:   Synopsis:
2822: #include <petsc/private/hashmapiv.h>
2823:   PetscErrorCode PetscHMapIVQueryDel(PetscHMapIV ht, PetscInt key, PetscBool *present)

2825:   Input Parameters:
2826: + ht  - The hash table
2827: - key - The key

2829:   Output Parameter:
2830: . present - Boolean indicating whether the key was present

2832:   Level: developer

2834: .seealso: `PetscHMapIVQuerySet()`, `PetscHMapIVDel()`
2835: M*/

2837: /*MC
2838:   PetscHMapIVFind - Query for key in the hash table

2840:   Synopsis:
2841: #include <petsc/private/hashmapiv.h>
2842:   PetscErrorCode PetscHMapIVFind(PetscHMapIV ht, PetscInt key, PetscHashIter *iter, PetscBool *found)

2844:   Input Parameters:
2845: + ht  - The hash table
2846: - key - The key

2848:   Output Parameters:
2849: + iter - Iterator referencing the value for key
2850: - found - Boolean indicating whether the key was present

2852:   Level: developer

2854: .seealso: `PetscHMapIVIterGet()`, `PetscHMapIVIterDel()`
2855: M*/

2857: /*MC
2858:   PetscHMapIVPut - Set a key in the hash table

2860:   Synopsis:
2861: #include <petsc/private/hashmapiv.h>
2862:   PetscErrorCode PetscHMapIVPut(PetscHMapIV ht, PetscInt key, PetscHashIter *iter, PetscBool *missing)

2864:   Input Parameters:
2865: + ht  - The hash table
2866: - key - The key

2868:   Output Parameters:
2869: + iter - Iterator referencing the value for key
2870: - missing - Boolean indicating whether the key was missing

2872:   Level: developer

2874: .seealso: `PetscHMapIVIterSet()`, `PetscHMapIVQuerySet()`, `PetscHMapIVSet()`,
2875: `PetscHMapIVSetWithMode()`
2876: M*/

2878: /*MC
2879:   PetscHMapIVIterGet - Get the value referenced by an iterator in the hash table

2881:   Synopsis:
2882: #include <petsc/private/hashmapiv.h>
2883:   PetscErrorCode PetscHMapIVIterGet(PetscHMapIV ht, PetscHashIter iter, PetscScalar *val)

2885:   Input Parameters:
2886: + ht   - The hash table
2887: - iter - The iterator

2889:   Output Parameter:
2890: . val  - The value

2892:   Level: developer

2894: .seealso: `PetscHMapIVFind()`, `PetscHMapIVGet()`, `PetscHMapIVGetWithDefault()`
2895: M*/

2897: /*MC
2898:   PetscHMapIVIterSet - Set the value referenced by an iterator in the hash

2900:   Synopsis:
2901: #include <petsc/private/hashmapiv.h>
2902:   PetscErrorCode PetscHMapIVIterSet(PetscHMapIV ht, PetscHashIter iter, PetscScalar val)

2904:   Input Parameters:
2905: + ht   - The hash table
2906: . iter - The iterator
2907: - val  - The value

2909:   Level: developer

2911: .seealso: `PetscHMapIVPut()`, `PetscHMapIVQuerySet()`, `PetscHMapIVSet()`,
2912: `PetscHMapIVSetWithMode()`
2913: M*/

2915: /*MC
2916:   PetscHMapIVIterDel - Remove the (key,value) referenced by an iterator from the hash table

2918:   Synopsis:
2919: #include <petsc/private/hashmapiv.h>
2920:   PetscErrorCode PetscHMapIVIterDel(PetscHMapIV ht, PetscHashIter iter)

2922:   Input Parameters:
2923: + ht   - The hash table
2924: - iter - The iterator

2926:   Level: developer

2928: .seealso: `PetscHMapIVFind()`, `PetscHMapIVQueryDel()`, `PetscHMapIVDel()`
2929: M*/

2931: /*MC
2932:   PetscHMapIVGetKeys - Get all keys from a hash table

2934:   Synopsis:
2935: #include <petsc/private/hashmapiv.h>
2936:   PetscErrorCode PetscHMapIVGetKeys(PetscHMapIV ht, PetscInt *off, PetscInt array[])

2938:   Input Parameters:
2939: + ht    - The hash table
2940: . off   - Input offset in array (usually zero)
2941: - array - Array to put hash table keys in

2943:   Output Parameters:
2944: + off   - Output offset in array (output offset = input offset + hash table size)
2945: - array - Array filled with the hash table keys

2947:   Level: developer

2949: .seealso: `PetscHSetIVGetSize()`, `PetscHMapIVGetVals()`
2950: M*/

2952: /*MC
2953:   PetscHMapIVGetVals - Get all values from a hash table

2955:   Synopsis:
2956: #include <petsc/private/hashmapiv.h>
2957:   PetscErrorCode PetscHMapIVGetVals(PetscHMapIV ht, PetscInt *off, PetscScalar array[])

2959:   Input Parameters:
2960: + ht    - The hash table
2961: . off   - Input offset in array (usually zero)
2962: - array - Array to put hash table values in

2964:   Output Parameters:
2965: + off   - Output offset in array (output offset = input offset + hash table size)
2966: - array - Array filled with the hash table values

2968:   Level: developer

2970: .seealso: `PetscHSetIVGetSize()`, `PetscHMapIVGetKeys()`
2971: M*/

2973: /*MC
2974:   PetscHMapIVGetPairs - Get all (key,value) pairs from a hash table

2976:   Synopsis:
2977: #include <petsc/private/hashmapiv.h>
2978:   PetscErrorCode PetscHMapIVGetPairs(PetscHMapIV ht, PetscInt *off, PetscInt karray[], PetscScalar varray[])

2980:   Input Parameters:
2981: + ht    - The hash table
2982: . off   - Input offset in array (usually zero)
2983: . karray - Array to put hash table keys in
2984: - varray - Array to put hash table values in

2986:   Output Parameters:
2987: + off   - Output offset in array (output offset = input offset + hash table size)
2988: . karray - Array filled with the hash table keys
2989: - varray - Array filled with the hash table values

2991:   Level: developer

2993: .seealso: `PetscHSetIVGetSize()`, `PetscHMapIVGetKeys()`, `PetscHMapIVGetVals()`
2994: M*/
2995: /* SUBMANSEC = PetscH */

2997: This file is processed by make allmanpages in $PETSC_DIR/makefile to create manual pages
2998: for the types and macros created by PETSC_HASH_MAP(). For example, PetscHMAPIJ.

3000: /*S
3001:   PetscHMapObj - Hash table map with a key of PetscInt64

3003:   Synopsis:
3004:   typedef khash_t(HMapObj) *PetscHMapObj;

3006:   Level: developer

3008: .seealso: `PETSC_HASH_MAP()`, `PetscHMapObjCreate()`, `PETSC_HASH_SET()`, `PetscHSetObjCreate()`
3009: S*/
3010: typedef struct _PetscHashObj PetscHMapObj;

3012: /*MC
3013:   PetscHMapObjCreate - Create a hash table

3015:   Synopsis:
3016: #include <petsc/private/hashmapobj.h>
3017:   PetscErrorCode PetscHMapObjCreate(PetscHMapObj *ht)

3019:   Output Parameter:
3020: . ht - The hash table

3022:   Level: developer

3024: .seealso: `PetscHMapObjCreateWithSize()`, `PetscHMapObjDestroy()`
3025: M*/

3027: /*MC
3028:   PetscHMapObjCreateWithSize - Create a hash table with a given initial size

3030:   Synopsis:
3031: #include <petsc/private/hashmapobj.h>
3032:   PetscErrorCode PetscHMapObjCreateWithSize(PetscInt n, PetscHMapObj *ht)

3034:   Input Parameter:
3035: . n - The size of the hash table

3037:   Output Parameter:
3038: . ht - The hash table

3040:   Level: developer

3042:   Note:
3043:   `n` must be non-negative.

3045: .seealso: `PetscHMapObjCreate()`, `PetscHMapObjDestroy()`
3046: M*/

3048: /*MC
3049:   PetscHMapObjDestroy - Destroy a hash table

3051:   Synopsis:
3052: #include <petsc/private/hashmapobj.h>
3053:   PetscErrorCode PetscHMapObjDestroy(PetscHMapObj *ht)

3055:   Input Parameter:
3056: . ht - The hash table

3058:   Level: developer

3060: .seealso: `PetscHMapObjCreate()`, `PetscHMapObjCreateWithSize()`
3061: M*/

3063: /*MC
3064:   PetscHMapObjReset - Reset a hash table

3066:   Synopsis:
3067: #include <petsc/private/hashmapobj.h>
3068:   PetscErrorCode PetscHMapObjReset(PetscHMapObj ht)

3070:   Input Parameter:
3071: . ht - The hash table

3073:   Level: developer

3075: .seealso: `PetscHMapObjClear()`
3076: M*/

3078: /*MC
3079:   PetscHMapObjDuplicate - Duplicate a hash table

3081:   Synopsis:
3082: #include <petsc/private/hashmapobj.h>
3083:   PetscErrorCode PetscHMapObjDuplicate(PetscHMapObj ht, PetscHMapObj *hd)

3085:   Input Parameter:
3086: . ht - The source hash table

3088:   Output Parameter:
3089: . ht - The duplicated hash table

3091:   Level: developer

3093: .seealso: `PetscHMapObjCreate()`
3094: M*/

3096: /*MC
3097:   PetscHMapObjClear - Clear a hash table

3099:   Synopsis:
3100: #include <petsc/private/hashmapobj.h>
3101:   PetscErrorCode PetscHMapObjClear(PetscHMapObj ht)

3103:   Input Parameter:
3104: . ht - The hash table

3106:   Level: developer

3108: .seealso: `PetscHMapObjReset()`
3109: M*/

3111: /*MC
3112:   PetscHMapObjResize - Set the number of buckets in a hash table

3114:   Synopsis:
3115: #include <petsc/private/hashmapobj.h>
3116:   PetscErrorCode PetscHMapObjResize(PetscHMapObj ht, PetscInt nb)

3118:   Input Parameters:
3119: + ht - The hash table
3120: - nb - The number of buckets

3122:   Level: developer

3124: .seealso: `PetscHMapObjCreate()`
3125: M*/

3127: /*MC
3128:   PetscHMapObjGetSize - Get the number of entries in a hash table

3130:   Synopsis:
3131: #include <petsc/private/hashmapobj.h>
3132:   PetscErrorCode PetscHMapObjGetSize(PetscHMapObj ht, PetscInt *n)

3134:   Input Parameter:
3135: . ht - The hash table

3137:   Output Parameter:
3138: . n - The number of entries

3140:   Level: developer

3142: .seealso: `PetscHMapObjResize()`
3143: M*/

3145: /*MC
3146:   PetscHMapObjGetCapacity - Get the current size of the array in the hash table

3148:   Synopsis:
3149: #include <petsc/private/hashmapobj.h>
3150:   PetscErrorCode PetscHMapObjGetCapacity(PetscHMapObj ht, PetscInt *n)

3152:   Input Parameter:
3153: . ht - The hash table

3155:   Output Parameter:
3156: . n - The capacity

3158:   Level: developer

3160: .seealso: `PetscHMapObjResize()`, `PetscHMapObjGetSize()`
3161: M*/

3163: /*MC
3164:   PetscHMapObjHas - Query for a key in the hash table

3166:   Synopsis:
3167: #include <petsc/private/hashmapobj.h>
3168:   PetscErrorCode PetscHMapObjHas(PetscHMapObj ht, PetscInt64 key, PetscBool *has)

3170:   Input Parameters:
3171: + ht  - The hash table
3172: - key - The key

3174:   Output Parameter:
3175: . has - Boolean indicating whether key is in the hash table

3177:   Level: developer

3179: .seealso: `PetscHMapObjGet()`, `PetscHMapObjGetWithDefault()`, `PetscHMapObjSet()`,
3180: `PetscHMapObjSetWithMode()`, `PetscHMapObjFind()`
3181: M*/

3183: /*MC
3184:   PetscHMapObjGet - Get the value for a key in the hash table

3186:   Synopsis:
3187: #include <petsc/private/hashmapobj.h>
3188:   PetscErrorCode PetscHMapObjGet(PetscHMapObj ht, PetscInt64 key, PetscObject *val)

3190:   Input Parameters:
3191: + ht  - The hash table
3192: - key - The key

3194:   Output Parameter:
3195: . val - The value

3197:   Level: developer

3199: .seealso: `PetscHMapObjSet()`, `PetscHMapObjSetWithMode()`, `PetscHMapObjIterGet()`,
3200: `PetscHMapObjGetWithDefault()`
3201: M*/

3203: /*MC
3204:   PetscHMapObjGetWithDefault - Get the value for a key in the hash table but override the default
3205:   value returned if the key was not found

3207:   Synopsis:
3208: #include <petsc/private/hashmapobj.h>
3209:   PetscErrorCode PetscHMapObjGetWithDefault(PetscHMapObj ht, PetscInt64 key, PetscObject default_val, PetscObject *val)

3211:   Input Parameters:
3212: + ht          - The hash table
3213: . key         - The key
3214: - default_val - The default value to set `val` to if `key` was not found

3216:   Output Parameter:
3217: . val - The value

3219:   Level: developer

3221: .seealso: `PetscHMapObjGet()`, `PetscHMapObjSet()`, `PetscHMapObjSetWithMode()`, `PetscHMapObjIterGet()`
3222: M*/


3225: /*MC
3226:   PetscHMapObjSet - Set a (key,value) entry in the hash table

3228:   Synopsis:
3229: #include <petsc/private/hashmapobj.h>
3230:   PetscErrorCode PetscHMapObjSet(PetscHMapObj ht, PetscInt64 key, PetscObject val)

3232:   Input Parameters:
3233: + ht  - The hash table
3234: . key - The key
3235: - val - The value

3237:   Level: developer

3239: .seealso: `PetscHMapObjGet()`, `PetscHMapObjSetWithMode()`, `PetscHMapObjGetWithDefault()`,
3240: `PetscHMapObjIterSet()`
3241: M*/

3243: /*MC
3244:   PetscHMapObjSetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode`

3246:   Synopsis:
3247: #include <petsc/private/hashmapobj.h>
3248:   PetscErrorCode PetscHMapObjSetWithMode(PetscHMapObj ht, PetscInt64 key, PetscObject val, InsertMode mode)

3250:   Input Parameters:
3251: + ht   - The hash table
3252: . key  - The key
3253: . val  - The value
3254: - mode - The insertion mode

3256:   Level: developer

3258:   Notes:
3259:   `mode` may be any of the following\:
3260:   - `INSERT_VALUES`\: this routine behaves identically to `PetscHMapObjSet()`.
3261:   - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`)
3262:                    is inserted into `ht` as-if-by `INSERT_VALUES`.
3263:   - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the
3264:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
3265:                    `INSERT_VALUES`.
3266:   - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the
3267:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
3268:                    `INSERT_VALUES`.

3270:    All other `InsertMode` values raise an error.

3272:    Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type
3273:    it is not available by default for all PETSc hash table instantiations. If a particular
3274:    instantiation supports this routine it must define `PETSC_HMAPObj_HAVE_EXTENDED_API` to
3275:    `1`.

3277: .seealso: `PetscHMapObjSet()`, `PetscHMapObjGet()`, `PetscHMapObjGetWithDefault()`,
3278: `PetscHMapObjIterSet()`
3279: M*/

3281: /*MC
3282:   PetscHMapObjDel - Remove a key and its value from the hash table

3284:   Synopsis:
3285: #include <petsc/private/hashmapobj.h>
3286:   PetscErrorCode PetscHMapObjDel(PetscHMapObj ht,PetscInt64 key)

3288:   Input Parameters:
3289: + ht  - The hash table
3290: - key - The key

3292:   Level: developer

3294: .seealso: `PetscHMapObjHas()`, `PetscHMapObjIterDel()`
3295: M*/

3297: /*MC
3298:   PetscHMapObjQuerySet - Query and set a (key,value) entry in the hash table

3300:   Synopsis:
3301: #include <petsc/private/hashmapobj.h>
3302:   PetscErrorCode PetscHMapObjQuerySet(PetscHMapObj ht, PetscInt64 key, PetscObject val, PetscBool *missing)

3304:   Input Parameters:
3305: + ht  - The hash table
3306: . key - The key
3307: - val - The value

3309:   Output Parameter:
3310: . missing - Boolean indicating whether the key was missing

3312:   Level: developer

3314: .seealso: `PetscHMapObjQueryDel()`, `PetscHMapObjSet()`, `PetscHMapObjSetWithMode()`
3315: M*/

3317: /*MC
3318:   PetscHMapObjQueryDel - Query and remove a (key,value) entry from the hash table

3320:   Synopsis:
3321: #include <petsc/private/hashmapobj.h>
3322:   PetscErrorCode PetscHMapObjQueryDel(PetscHMapObj ht, PetscInt64 key, PetscBool *present)

3324:   Input Parameters:
3325: + ht  - The hash table
3326: - key - The key

3328:   Output Parameter:
3329: . present - Boolean indicating whether the key was present

3331:   Level: developer

3333: .seealso: `PetscHMapObjQuerySet()`, `PetscHMapObjDel()`
3334: M*/

3336: /*MC
3337:   PetscHMapObjFind - Query for key in the hash table

3339:   Synopsis:
3340: #include <petsc/private/hashmapobj.h>
3341:   PetscErrorCode PetscHMapObjFind(PetscHMapObj ht, PetscInt64 key, PetscHashIter *iter, PetscBool *found)

3343:   Input Parameters:
3344: + ht  - The hash table
3345: - key - The key

3347:   Output Parameters:
3348: + iter - Iterator referencing the value for key
3349: - found - Boolean indicating whether the key was present

3351:   Level: developer

3353: .seealso: `PetscHMapObjIterGet()`, `PetscHMapObjIterDel()`
3354: M*/

3356: /*MC
3357:   PetscHMapObjPut - Set a key in the hash table

3359:   Synopsis:
3360: #include <petsc/private/hashmapobj.h>
3361:   PetscErrorCode PetscHMapObjPut(PetscHMapObj ht, PetscInt64 key, PetscHashIter *iter, PetscBool *missing)

3363:   Input Parameters:
3364: + ht  - The hash table
3365: - key - The key

3367:   Output Parameters:
3368: + iter - Iterator referencing the value for key
3369: - missing - Boolean indicating whether the key was missing

3371:   Level: developer

3373: .seealso: `PetscHMapObjIterSet()`, `PetscHMapObjQuerySet()`, `PetscHMapObjSet()`,
3374: `PetscHMapObjSetWithMode()`
3375: M*/

3377: /*MC
3378:   PetscHMapObjIterGet - Get the value referenced by an iterator in the hash table

3380:   Synopsis:
3381: #include <petsc/private/hashmapobj.h>
3382:   PetscErrorCode PetscHMapObjIterGet(PetscHMapObj ht, PetscHashIter iter, PetscObject *val)

3384:   Input Parameters:
3385: + ht   - The hash table
3386: - iter - The iterator

3388:   Output Parameter:
3389: . val  - The value

3391:   Level: developer

3393: .seealso: `PetscHMapObjFind()`, `PetscHMapObjGet()`, `PetscHMapObjGetWithDefault()`
3394: M*/

3396: /*MC
3397:   PetscHMapObjIterSet - Set the value referenced by an iterator in the hash

3399:   Synopsis:
3400: #include <petsc/private/hashmapobj.h>
3401:   PetscErrorCode PetscHMapObjIterSet(PetscHMapObj ht, PetscHashIter iter, PetscObject val)

3403:   Input Parameters:
3404: + ht   - The hash table
3405: . iter - The iterator
3406: - val  - The value

3408:   Level: developer

3410: .seealso: `PetscHMapObjPut()`, `PetscHMapObjQuerySet()`, `PetscHMapObjSet()`,
3411: `PetscHMapObjSetWithMode()`
3412: M*/

3414: /*MC
3415:   PetscHMapObjIterDel - Remove the (key,value) referenced by an iterator from the hash table

3417:   Synopsis:
3418: #include <petsc/private/hashmapobj.h>
3419:   PetscErrorCode PetscHMapObjIterDel(PetscHMapObj ht, PetscHashIter iter)

3421:   Input Parameters:
3422: + ht   - The hash table
3423: - iter - The iterator

3425:   Level: developer

3427: .seealso: `PetscHMapObjFind()`, `PetscHMapObjQueryDel()`, `PetscHMapObjDel()`
3428: M*/

3430: /*MC
3431:   PetscHMapObjGetKeys - Get all keys from a hash table

3433:   Synopsis:
3434: #include <petsc/private/hashmapobj.h>
3435:   PetscErrorCode PetscHMapObjGetKeys(PetscHMapObj ht, PetscInt *off, PetscInt64 array[])

3437:   Input Parameters:
3438: + ht    - The hash table
3439: . off   - Input offset in array (usually zero)
3440: - array - Array to put hash table keys in

3442:   Output Parameters:
3443: + off   - Output offset in array (output offset = input offset + hash table size)
3444: - array - Array filled with the hash table keys

3446:   Level: developer

3448: .seealso: `PetscHSetObjGetSize()`, `PetscHMapObjGetVals()`
3449: M*/

3451: /*MC
3452:   PetscHMapObjGetVals - Get all values from a hash table

3454:   Synopsis:
3455: #include <petsc/private/hashmapobj.h>
3456:   PetscErrorCode PetscHMapObjGetVals(PetscHMapObj ht, PetscInt *off, PetscObject array[])

3458:   Input Parameters:
3459: + ht    - The hash table
3460: . off   - Input offset in array (usually zero)
3461: - array - Array to put hash table values in

3463:   Output Parameters:
3464: + off   - Output offset in array (output offset = input offset + hash table size)
3465: - array - Array filled with the hash table values

3467:   Level: developer

3469: .seealso: `PetscHSetObjGetSize()`, `PetscHMapObjGetKeys()`
3470: M*/

3472: /*MC
3473:   PetscHMapObjGetPairs - Get all (key,value) pairs from a hash table

3475:   Synopsis:
3476: #include <petsc/private/hashmapobj.h>
3477:   PetscErrorCode PetscHMapObjGetPairs(PetscHMapObj ht, PetscInt *off, PetscInt64 karray[], PetscObject varray[])

3479:   Input Parameters:
3480: + ht    - The hash table
3481: . off   - Input offset in array (usually zero)
3482: . karray - Array to put hash table keys in
3483: - varray - Array to put hash table values in

3485:   Output Parameters:
3486: + off   - Output offset in array (output offset = input offset + hash table size)
3487: . karray - Array filled with the hash table keys
3488: - varray - Array filled with the hash table values

3490:   Level: developer

3492: .seealso: `PetscHSetObjGetSize()`, `PetscHMapObjGetKeys()`, `PetscHMapObjGetVals()`
3493: M*/