Actual source code: hashmap.txt.h
  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*/