Actual source code: hashmap.txt.h

      1: /* MANSEC = Sys */
      2: /* SUBMANSEC = PetscH */

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

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

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

     13:   Level: developer

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

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

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

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

     29:   Level: developer

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

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

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

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

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

     47:   Level: developer

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

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

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

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

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

     65:   Level: developer

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

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

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

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

     80:   Level: developer

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

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

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

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

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

     98:   Level: developer

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

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

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

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

    113:   Level: developer

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

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

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

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

    129:   Level: developer

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

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

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

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

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

    147:   Level: developer

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

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

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

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

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

    165:   Level: developer

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

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

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

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

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

    184:   Level: developer

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

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

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

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

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

    204:   Level: developer

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

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

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

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

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

    226:   Level: developer

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

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

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

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

    244:   Level: developer

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

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

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

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

    263:   Level: developer

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

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

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

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

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

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

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

    299:   Level: developer

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

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

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

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

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

    319:   Level: developer

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

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

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

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

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

    338:   Level: developer

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

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

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

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

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

    358:   Level: developer

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

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

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

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

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

    378:   Level: developer

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

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

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

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

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

    398:   Level: developer

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

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

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

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

    415:   Level: developer

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

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

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

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

    432:   Level: developer

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

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

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

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

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

    453:   Level: developer

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

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

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

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

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

    474:   Level: developer

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

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

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

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

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

    497:   Level: developer

    499: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetKeys()`, `PetscHMapIGetVals()`
    500: M*/
    501: /* MANSEC = Sys */
    502: /* SUBMANSEC = PetscH */

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

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

    510:   Synopsis:
    511:   typedef khash_t(HMapIJ) *PetscHMapIJ;

    513:   Level: developer

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

    519: /*MC
    520:   PetscHMapIJCreate - Create a hash table

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

    526:   Output Parameter:
    527: . ht - The hash table

    529:   Level: developer

    531: .seealso: `PetscHMapIJCreateWithSize()`, `PetscHMapIJDestroy()`
    532: M*/

    534: /*MC
    535:   PetscHMapIJCreateWithSize - Create a hash table with a given initial size

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

    541:   Input Parameter:
    542: . n - The size of the hash table

    544:   Output Parameter:
    545: . ht - The hash table

    547:   Level: developer

    549:   Note:
    550:   `n` must be non-negative.

    552: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJDestroy()`
    553: M*/

    555: /*MC
    556:   PetscHMapIJDestroy - Destroy a hash table

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

    562:   Input Parameter:
    563: . ht - The hash table

    565:   Level: developer

    567: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJCreateWithSize()`
    568: M*/

    570: /*MC
    571:   PetscHMapIJReset - Reset a hash table

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

    577:   Input Parameter:
    578: . ht - The hash table

    580:   Level: developer

    582: .seealso: `PetscHMapIJClear()`
    583: M*/

    585: /*MC
    586:   PetscHMapIJDuplicate - Duplicate a hash table

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

    592:   Input Parameter:
    593: . ht - The source hash table

    595:   Output Parameter:
    596: . ht - The duplicated hash table

    598:   Level: developer

    600: .seealso: `PetscHMapIJCreate()`
    601: M*/

    603: /*MC
    604:   PetscHMapIJClear - Clear a hash table

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

    610:   Input Parameter:
    611: . ht - The hash table

    613:   Level: developer

    615: .seealso: `PetscHMapIJReset()`
    616: M*/

    618: /*MC
    619:   PetscHMapIJResize - Set the number of buckets in a hash table

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

    625:   Input Parameters:
    626: + ht - The hash table
    627: - nb - The number of buckets

    629:   Level: developer

    631: .seealso: `PetscHMapIJCreate()`
    632: M*/

    634: /*MC
    635:   PetscHMapIJGetSize - Get the number of entries in a hash table

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

    641:   Input Parameter:
    642: . ht - The hash table

    644:   Output Parameter:
    645: . n - The number of entries

    647:   Level: developer

    649: .seealso: `PetscHMapIJResize()`
    650: M*/

    652: /*MC
    653:   PetscHMapIJGetCapacity - Get the current size of the array in the hash table

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

    659:   Input Parameter:
    660: . ht - The hash table

    662:   Output Parameter:
    663: . n - The capacity

    665:   Level: developer

    667: .seealso: `PetscHMapIJResize()`, `PetscHMapIJGetSize()`
    668: M*/

    670: /*MC
    671:   PetscHMapIJHas - Query for a key in the hash table

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

    677:   Input Parameters:
    678: + ht  - The hash table
    679: - key - The key

    681:   Output Parameter:
    682: . has - Boolean indicating whether key is in the hash table

    684:   Level: developer

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

    690: /*MC
    691:   PetscHMapIJGet - Get the value for a key in the hash table

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

    697:   Input Parameters:
    698: + ht  - The hash table
    699: - key - The key

    701:   Output Parameter:
    702: . val - The value

    704:   Level: developer

    706: .seealso: `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`,
    707: `PetscHMapIJGetWithDefault()`
    708: M*/

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

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

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

    723:   Output Parameter:
    724: . val - The value

    726:   Level: developer

    728: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`
    729: M*/

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

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

    739:   Input Parameters:
    740: + ht  - The hash table
    741: . key - The key
    742: - val - The value

    744:   Level: developer

    746: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJGetWithDefault()`,
    747: `PetscHMapIJIterSet()`
    748: M*/

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

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

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

    763:   Level: developer

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

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

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

    784: .seealso: `PetscHMapIJSet()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`,
    785: `PetscHMapIJIterSet()`
    786: M*/

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

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

    795:   Input Parameters:
    796: + ht  - The hash table
    797: - key - The key

    799:   Level: developer

    801: .seealso: `PetscHMapIJHas()`, `PetscHMapIJIterDel()`
    802: M*/

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

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

    811:   Input Parameters:
    812: + ht  - The hash table
    813: . key - The key
    814: - val - The value

    816:   Output Parameter:
    817: . missing - Boolean indicating whether the key was missing

    819:   Level: developer

    821: .seealso: `PetscHMapIJQueryDel()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`
    822: M*/

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

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

    831:   Input Parameters:
    832: + ht  - The hash table
    833: - key - The key

    835:   Output Parameter:
    836: . present - Boolean indicating whether the key was present

    838:   Level: developer

    840: .seealso: `PetscHMapIJQuerySet()`, `PetscHMapIJDel()`
    841: M*/

    843: /*MC
    844:   PetscHMapIJFind - Query for key in the hash table

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

    850:   Input Parameters:
    851: + ht  - The hash table
    852: - key - The key

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

    858:   Level: developer

    860: .seealso: `PetscHMapIJIterGet()`, `PetscHMapIJIterDel()`
    861: M*/

    863: /*MC
    864:   PetscHMapIJPut - Set a key in the hash table

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

    870:   Input Parameters:
    871: + ht  - The hash table
    872: - key - The key

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

    878:   Level: developer

    880: .seealso: `PetscHMapIJIterSet()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
    881: `PetscHMapIJSetWithMode()`
    882: M*/

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

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

    891:   Input Parameters:
    892: + ht   - The hash table
    893: - iter - The iterator

    895:   Output Parameter:
    896: . val  - The value

    898:   Level: developer

    900: .seealso: `PetscHMapIJFind()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`
    901: M*/

    903: /*MC
    904:   PetscHMapIJIterSet - Set the value referenced by an iterator in the hash

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

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

    915:   Level: developer

    917: .seealso: `PetscHMapIJPut()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
    918: `PetscHMapIJSetWithMode()`
    919: M*/

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

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

    928:   Input Parameters:
    929: + ht   - The hash table
    930: - iter - The iterator

    932:   Level: developer

    934: .seealso: `PetscHMapIJFind()`, `PetscHMapIJQueryDel()`, `PetscHMapIJDel()`
    935: M*/

    937: /*MC
    938:   PetscHMapIJGetKeys - Get all keys from a hash table

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

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

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

    953:   Level: developer

    955: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetVals()`
    956: M*/

    958: /*MC
    959:   PetscHMapIJGetVals - Get all values from a hash table

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

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

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

    974:   Level: developer

    976: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`
    977: M*/

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

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

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

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

    997:   Level: developer

    999: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`, `PetscHMapIJGetVals()`
    1000: M*/
    1001: /* MANSEC = Sys */
    1002: /* SUBMANSEC = PetscH */

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

    1007: /*S
    1008:   PetscHMapI - Hash table map with a key of PetscInt

    1010:   Synopsis:
    1011:   typedef khash_t(HMapI) *PetscHMapI;

    1013:   Level: developer

    1015: .seealso: `PETSC_HASH_MAP()`, `PetscHMapICreate()`, `PETSC_HASH_SET()`, `PetscHSetICreate()`
    1016: S*/
    1017: typedef struct _PetscHashI PetscHMapI;

    1019: /*MC
    1020:   PetscHMapICreate - Create a hash table

    1022:   Synopsis:
    1023: #include <petsc/private/hashmapi.h>
    1024:   PetscErrorCode PetscHMapICreate(PetscHMapI *ht)

    1026:   Output Parameter:
    1027: . ht - The hash table

    1029:   Level: developer

    1031: .seealso: `PetscHMapICreateWithSize()`, `PetscHMapIDestroy()`
    1032: M*/

    1034: /*MC
    1035:   PetscHMapICreateWithSize - Create a hash table with a given initial size

    1037:   Synopsis:
    1038: #include <petsc/private/hashmapi.h>
    1039:   PetscErrorCode PetscHMapICreateWithSize(PetscInt n, PetscHMapI *ht)

    1041:   Input Parameter:
    1042: . n - The size of the hash table

    1044:   Output Parameter:
    1045: . ht - The hash table

    1047:   Level: developer

    1049:   Note:
    1050:   `n` must be non-negative.

    1052: .seealso: `PetscHMapICreate()`, `PetscHMapIDestroy()`
    1053: M*/

    1055: /*MC
    1056:   PetscHMapIDestroy - Destroy a hash table

    1058:   Synopsis:
    1059: #include <petsc/private/hashmapi.h>
    1060:   PetscErrorCode PetscHMapIDestroy(PetscHMapI *ht)

    1062:   Input Parameter:
    1063: . ht - The hash table

    1065:   Level: developer

    1067: .seealso: `PetscHMapICreate()`, `PetscHMapICreateWithSize()`
    1068: M*/

    1070: /*MC
    1071:   PetscHMapIReset - Reset a hash table

    1073:   Synopsis:
    1074: #include <petsc/private/hashmapi.h>
    1075:   PetscErrorCode PetscHMapIReset(PetscHMapI ht)

    1077:   Input Parameter:
    1078: . ht - The hash table

    1080:   Level: developer

    1082: .seealso: `PetscHMapIClear()`
    1083: M*/

    1085: /*MC
    1086:   PetscHMapIDuplicate - Duplicate a hash table

    1088:   Synopsis:
    1089: #include <petsc/private/hashmapi.h>
    1090:   PetscErrorCode PetscHMapIDuplicate(PetscHMapI ht, PetscHMapI *hd)

    1092:   Input Parameter:
    1093: . ht - The source hash table

    1095:   Output Parameter:
    1096: . ht - The duplicated hash table

    1098:   Level: developer

    1100: .seealso: `PetscHMapICreate()`
    1101: M*/

    1103: /*MC
    1104:   PetscHMapIClear - Clear a hash table

    1106:   Synopsis:
    1107: #include <petsc/private/hashmapi.h>
    1108:   PetscErrorCode PetscHMapIClear(PetscHMapI ht)

    1110:   Input Parameter:
    1111: . ht - The hash table

    1113:   Level: developer

    1115: .seealso: `PetscHMapIReset()`
    1116: M*/

    1118: /*MC
    1119:   PetscHMapIResize - Set the number of buckets in a hash table

    1121:   Synopsis:
    1122: #include <petsc/private/hashmapi.h>
    1123:   PetscErrorCode PetscHMapIResize(PetscHMapI ht, PetscInt nb)

    1125:   Input Parameters:
    1126: + ht - The hash table
    1127: - nb - The number of buckets

    1129:   Level: developer

    1131: .seealso: `PetscHMapICreate()`
    1132: M*/

    1134: /*MC
    1135:   PetscHMapIGetSize - Get the number of entries in a hash table

    1137:   Synopsis:
    1138: #include <petsc/private/hashmapi.h>
    1139:   PetscErrorCode PetscHMapIGetSize(PetscHMapI ht, PetscInt *n)

    1141:   Input Parameter:
    1142: . ht - The hash table

    1144:   Output Parameter:
    1145: . n - The number of entries

    1147:   Level: developer

    1149: .seealso: `PetscHMapIResize()`
    1150: M*/

    1152: /*MC
    1153:   PetscHMapIGetCapacity - Get the current size of the array in the hash table

    1155:   Synopsis:
    1156: #include <petsc/private/hashmapi.h>
    1157:   PetscErrorCode PetscHMapIGetCapacity(PetscHMapI ht, PetscInt *n)

    1159:   Input Parameter:
    1160: . ht - The hash table

    1162:   Output Parameter:
    1163: . n - The capacity

    1165:   Level: developer

    1167: .seealso: `PetscHMapIResize()`, `PetscHMapIGetSize()`
    1168: M*/

    1170: /*MC
    1171:   PetscHMapIHas - Query for a key in the hash table

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

    1177:   Input Parameters:
    1178: + ht  - The hash table
    1179: - key - The key

    1181:   Output Parameter:
    1182: . has - Boolean indicating whether key is in the hash table

    1184:   Level: developer

    1186: .seealso: `PetscHMapIGet()`, `PetscHMapIGetWithDefault()`, `PetscHMapISet()`,
    1187: `PetscHMapISetWithMode()`, `PetscHMapIFind()`
    1188: M*/

    1190: /*MC
    1191:   PetscHMapIGet - Get the value for a key in the hash table

    1193:   Synopsis:
    1194: #include <petsc/private/hashmapi.h>
    1195:   PetscErrorCode PetscHMapIGet(PetscHMapI ht, PetscInt key, PetscInt *val)

    1197:   Input Parameters:
    1198: + ht  - The hash table
    1199: - key - The key

    1201:   Output Parameter:
    1202: . val - The value

    1204:   Level: developer

    1206: .seealso: `PetscHMapISet()`, `PetscHMapISetWithMode()`, `PetscHMapIIterGet()`,
    1207: `PetscHMapIGetWithDefault()`
    1208: M*/

    1210: /*MC
    1211:   PetscHMapIGetWithDefault - Get the value for a key in the hash table but override the default
    1212:   value returned if the key was not found

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

    1218:   Input Parameters:
    1219: + ht          - The hash table
    1220: . key         - The key
    1221: - default_val - The default value to set `val` to if `key` was not found

    1223:   Output Parameter:
    1224: . val - The value

    1226:   Level: developer

    1228: .seealso: `PetscHMapIGet()`, `PetscHMapISet()`, `PetscHMapISetWithMode()`, `PetscHMapIIterGet()`
    1229: M*/

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

    1235:   Synopsis:
    1236: #include <petsc/private/hashmapi.h>
    1237:   PetscErrorCode PetscHMapISet(PetscHMapI ht, PetscInt key, PetscInt val)

    1239:   Input Parameters:
    1240: + ht  - The hash table
    1241: . key - The key
    1242: - val - The value

    1244:   Level: developer

    1246: .seealso: `PetscHMapIGet()`, `PetscHMapISetWithMode()`, `PetscHMapIGetWithDefault()`,
    1247: `PetscHMapIIterSet()`
    1248: M*/

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

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

    1257:   Input Parameters:
    1258: + ht   - The hash table
    1259: . key  - The key
    1260: . val  - The value
    1261: - mode - The insertion mode

    1263:   Level: developer

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

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

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

    1284: .seealso: `PetscHMapISet()`, `PetscHMapIGet()`, `PetscHMapIGetWithDefault()`,
    1285: `PetscHMapIIterSet()`
    1286: M*/

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

    1291:   Synopsis:
    1292: #include <petsc/private/hashmapi.h>
    1293:   PetscErrorCode PetscHMapIDel(PetscHMapI ht,PetscInt key)

    1295:   Input Parameters:
    1296: + ht  - The hash table
    1297: - key - The key

    1299:   Level: developer

    1301: .seealso: `PetscHMapIHas()`, `PetscHMapIIterDel()`
    1302: M*/

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

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

    1311:   Input Parameters:
    1312: + ht  - The hash table
    1313: . key - The key
    1314: - val - The value

    1316:   Output Parameter:
    1317: . missing - Boolean indicating whether the key was missing

    1319:   Level: developer

    1321: .seealso: `PetscHMapIQueryDel()`, `PetscHMapISet()`, `PetscHMapISetWithMode()`
    1322: M*/

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

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

    1331:   Input Parameters:
    1332: + ht  - The hash table
    1333: - key - The key

    1335:   Output Parameter:
    1336: . present - Boolean indicating whether the key was present

    1338:   Level: developer

    1340: .seealso: `PetscHMapIQuerySet()`, `PetscHMapIDel()`
    1341: M*/

    1343: /*MC
    1344:   PetscHMapIFind - Query for key in the hash table

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

    1350:   Input Parameters:
    1351: + ht  - The hash table
    1352: - key - The key

    1354:   Output Parameters:
    1355: + iter - Iterator referencing the value for key
    1356: - found - Boolean indicating whether the key was present

    1358:   Level: developer

    1360: .seealso: `PetscHMapIIterGet()`, `PetscHMapIIterDel()`
    1361: M*/

    1363: /*MC
    1364:   PetscHMapIPut - Set a key in the hash table

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

    1370:   Input Parameters:
    1371: + ht  - The hash table
    1372: - key - The key

    1374:   Output Parameters:
    1375: + iter - Iterator referencing the value for key
    1376: - missing - Boolean indicating whether the key was missing

    1378:   Level: developer

    1380: .seealso: `PetscHMapIIterSet()`, `PetscHMapIQuerySet()`, `PetscHMapISet()`,
    1381: `PetscHMapISetWithMode()`
    1382: M*/

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

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

    1391:   Input Parameters:
    1392: + ht   - The hash table
    1393: - iter - The iterator

    1395:   Output Parameter:
    1396: . val  - The value

    1398:   Level: developer

    1400: .seealso: `PetscHMapIFind()`, `PetscHMapIGet()`, `PetscHMapIGetWithDefault()`
    1401: M*/

    1403: /*MC
    1404:   PetscHMapIIterSet - Set the value referenced by an iterator in the hash

    1406:   Synopsis:
    1407: #include <petsc/private/hashmapi.h>
    1408:   PetscErrorCode PetscHMapIIterSet(PetscHMapI ht, PetscHashIter iter, PetscInt val)

    1410:   Input Parameters:
    1411: + ht   - The hash table
    1412: . iter - The iterator
    1413: - val  - The value

    1415:   Level: developer

    1417: .seealso: `PetscHMapIPut()`, `PetscHMapIQuerySet()`, `PetscHMapISet()`,
    1418: `PetscHMapISetWithMode()`
    1419: M*/

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

    1424:   Synopsis:
    1425: #include <petsc/private/hashmapi.h>
    1426:   PetscErrorCode PetscHMapIIterDel(PetscHMapI ht, PetscHashIter iter)

    1428:   Input Parameters:
    1429: + ht   - The hash table
    1430: - iter - The iterator

    1432:   Level: developer

    1434: .seealso: `PetscHMapIFind()`, `PetscHMapIQueryDel()`, `PetscHMapIDel()`
    1435: M*/

    1437: /*MC
    1438:   PetscHMapIGetKeys - Get all keys from a hash table

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

    1444:   Input Parameters:
    1445: + ht    - The hash table
    1446: . off   - Input offset in array (usually zero)
    1447: - array - Array to put hash table keys in

    1449:   Output Parameters:
    1450: + off   - Output offset in array (output offset = input offset + hash table size)
    1451: - array - Array filled with the hash table keys

    1453:   Level: developer

    1455: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetVals()`
    1456: M*/

    1458: /*MC
    1459:   PetscHMapIGetVals - Get all values from a hash table

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

    1465:   Input Parameters:
    1466: + ht    - The hash table
    1467: . off   - Input offset in array (usually zero)
    1468: - array - Array to put hash table values in

    1470:   Output Parameters:
    1471: + off   - Output offset in array (output offset = input offset + hash table size)
    1472: - array - Array filled with the hash table values

    1474:   Level: developer

    1476: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetKeys()`
    1477: M*/

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

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

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

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

    1497:   Level: developer

    1499: .seealso: `PetscHSetIGetSize()`, `PetscHMapIGetKeys()`, `PetscHMapIGetVals()`
    1500: M*/
    1501: /* MANSEC = Sys */
    1502: /* SUBMANSEC = PetscH */

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

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

    1510:   Synopsis:
    1511:   typedef khash_t(HMapIJ) *PetscHMapIJ;

    1513:   Level: developer

    1515: .seealso: `PETSC_HASH_MAP()`, `PetscHMapIJCreate()`, `PETSC_HASH_SET()`, `PetscHSetIJCreate()`
    1516: S*/
    1517: typedef struct _PetscHashIJ PetscHMapIJ;

    1519: /*MC
    1520:   PetscHMapIJCreate - Create a hash table

    1522:   Synopsis:
    1523: #include <petsc/private/hashmapij.h>
    1524:   PetscErrorCode PetscHMapIJCreate(PetscHMapIJ *ht)

    1526:   Output Parameter:
    1527: . ht - The hash table

    1529:   Level: developer

    1531: .seealso: `PetscHMapIJCreateWithSize()`, `PetscHMapIJDestroy()`
    1532: M*/

    1534: /*MC
    1535:   PetscHMapIJCreateWithSize - Create a hash table with a given initial size

    1537:   Synopsis:
    1538: #include <petsc/private/hashmapij.h>
    1539:   PetscErrorCode PetscHMapIJCreateWithSize(PetscInt n, PetscHMapIJ *ht)

    1541:   Input Parameter:
    1542: . n - The size of the hash table

    1544:   Output Parameter:
    1545: . ht - The hash table

    1547:   Level: developer

    1549:   Note:
    1550:   `n` must be non-negative.

    1552: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJDestroy()`
    1553: M*/

    1555: /*MC
    1556:   PetscHMapIJDestroy - Destroy a hash table

    1558:   Synopsis:
    1559: #include <petsc/private/hashmapij.h>
    1560:   PetscErrorCode PetscHMapIJDestroy(PetscHMapIJ *ht)

    1562:   Input Parameter:
    1563: . ht - The hash table

    1565:   Level: developer

    1567: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJCreateWithSize()`
    1568: M*/

    1570: /*MC
    1571:   PetscHMapIJReset - Reset a hash table

    1573:   Synopsis:
    1574: #include <petsc/private/hashmapij.h>
    1575:   PetscErrorCode PetscHMapIJReset(PetscHMapIJ ht)

    1577:   Input Parameter:
    1578: . ht - The hash table

    1580:   Level: developer

    1582: .seealso: `PetscHMapIJClear()`
    1583: M*/

    1585: /*MC
    1586:   PetscHMapIJDuplicate - Duplicate a hash table

    1588:   Synopsis:
    1589: #include <petsc/private/hashmapij.h>
    1590:   PetscErrorCode PetscHMapIJDuplicate(PetscHMapIJ ht, PetscHMapIJ *hd)

    1592:   Input Parameter:
    1593: . ht - The source hash table

    1595:   Output Parameter:
    1596: . ht - The duplicated hash table

    1598:   Level: developer

    1600: .seealso: `PetscHMapIJCreate()`
    1601: M*/

    1603: /*MC
    1604:   PetscHMapIJClear - Clear a hash table

    1606:   Synopsis:
    1607: #include <petsc/private/hashmapij.h>
    1608:   PetscErrorCode PetscHMapIJClear(PetscHMapIJ ht)

    1610:   Input Parameter:
    1611: . ht - The hash table

    1613:   Level: developer

    1615: .seealso: `PetscHMapIJReset()`
    1616: M*/

    1618: /*MC
    1619:   PetscHMapIJResize - Set the number of buckets in a hash table

    1621:   Synopsis:
    1622: #include <petsc/private/hashmapij.h>
    1623:   PetscErrorCode PetscHMapIJResize(PetscHMapIJ ht, PetscInt nb)

    1625:   Input Parameters:
    1626: + ht - The hash table
    1627: - nb - The number of buckets

    1629:   Level: developer

    1631: .seealso: `PetscHMapIJCreate()`
    1632: M*/

    1634: /*MC
    1635:   PetscHMapIJGetSize - Get the number of entries in a hash table

    1637:   Synopsis:
    1638: #include <petsc/private/hashmapij.h>
    1639:   PetscErrorCode PetscHMapIJGetSize(PetscHMapIJ ht, PetscInt *n)

    1641:   Input Parameter:
    1642: . ht - The hash table

    1644:   Output Parameter:
    1645: . n - The number of entries

    1647:   Level: developer

    1649: .seealso: `PetscHMapIJResize()`
    1650: M*/

    1652: /*MC
    1653:   PetscHMapIJGetCapacity - Get the current size of the array in the hash table

    1655:   Synopsis:
    1656: #include <petsc/private/hashmapij.h>
    1657:   PetscErrorCode PetscHMapIJGetCapacity(PetscHMapIJ ht, PetscInt *n)

    1659:   Input Parameter:
    1660: . ht - The hash table

    1662:   Output Parameter:
    1663: . n - The capacity

    1665:   Level: developer

    1667: .seealso: `PetscHMapIJResize()`, `PetscHMapIJGetSize()`
    1668: M*/

    1670: /*MC
    1671:   PetscHMapIJHas - Query for a key in the hash table

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

    1677:   Input Parameters:
    1678: + ht  - The hash table
    1679: - key - The key

    1681:   Output Parameter:
    1682: . has - Boolean indicating whether key is in the hash table

    1684:   Level: developer

    1686: .seealso: `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`, `PetscHMapIJSet()`,
    1687: `PetscHMapIJSetWithMode()`, `PetscHMapIJFind()`
    1688: M*/

    1690: /*MC
    1691:   PetscHMapIJGet - Get the value for a key in the hash table

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

    1697:   Input Parameters:
    1698: + ht  - The hash table
    1699: - key - The key

    1701:   Output Parameter:
    1702: . val - The value

    1704:   Level: developer

    1706: .seealso: `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`,
    1707: `PetscHMapIJGetWithDefault()`
    1708: M*/

    1710: /*MC
    1711:   PetscHMapIJGetWithDefault - Get the value for a key in the hash table but override the default
    1712:   value returned if the key was not found

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

    1718:   Input Parameters:
    1719: + ht          - The hash table
    1720: . key         - The key
    1721: - default_val - The default value to set `val` to if `key` was not found

    1723:   Output Parameter:
    1724: . val - The value

    1726:   Level: developer

    1728: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`
    1729: M*/

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

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

    1739:   Input Parameters:
    1740: + ht  - The hash table
    1741: . key - The key
    1742: - val - The value

    1744:   Level: developer

    1746: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJGetWithDefault()`,
    1747: `PetscHMapIJIterSet()`
    1748: M*/

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

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

    1757:   Input Parameters:
    1758: + ht   - The hash table
    1759: . key  - The key
    1760: . val  - The value
    1761: - mode - The insertion mode

    1763:   Level: developer

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

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

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

    1784: .seealso: `PetscHMapIJSet()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`,
    1785: `PetscHMapIJIterSet()`
    1786: M*/

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

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

    1795:   Input Parameters:
    1796: + ht  - The hash table
    1797: - key - The key

    1799:   Level: developer

    1801: .seealso: `PetscHMapIJHas()`, `PetscHMapIJIterDel()`
    1802: M*/

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

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

    1811:   Input Parameters:
    1812: + ht  - The hash table
    1813: . key - The key
    1814: - val - The value

    1816:   Output Parameter:
    1817: . missing - Boolean indicating whether the key was missing

    1819:   Level: developer

    1821: .seealso: `PetscHMapIJQueryDel()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`
    1822: M*/

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

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

    1831:   Input Parameters:
    1832: + ht  - The hash table
    1833: - key - The key

    1835:   Output Parameter:
    1836: . present - Boolean indicating whether the key was present

    1838:   Level: developer

    1840: .seealso: `PetscHMapIJQuerySet()`, `PetscHMapIJDel()`
    1841: M*/

    1843: /*MC
    1844:   PetscHMapIJFind - Query for key in the hash table

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

    1850:   Input Parameters:
    1851: + ht  - The hash table
    1852: - key - The key

    1854:   Output Parameters:
    1855: + iter - Iterator referencing the value for key
    1856: - found - Boolean indicating whether the key was present

    1858:   Level: developer

    1860: .seealso: `PetscHMapIJIterGet()`, `PetscHMapIJIterDel()`
    1861: M*/

    1863: /*MC
    1864:   PetscHMapIJPut - Set a key in the hash table

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

    1870:   Input Parameters:
    1871: + ht  - The hash table
    1872: - key - The key

    1874:   Output Parameters:
    1875: + iter - Iterator referencing the value for key
    1876: - missing - Boolean indicating whether the key was missing

    1878:   Level: developer

    1880: .seealso: `PetscHMapIJIterSet()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
    1881: `PetscHMapIJSetWithMode()`
    1882: M*/

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

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

    1891:   Input Parameters:
    1892: + ht   - The hash table
    1893: - iter - The iterator

    1895:   Output Parameter:
    1896: . val  - The value

    1898:   Level: developer

    1900: .seealso: `PetscHMapIJFind()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`
    1901: M*/

    1903: /*MC
    1904:   PetscHMapIJIterSet - Set the value referenced by an iterator in the hash

    1906:   Synopsis:
    1907: #include <petsc/private/hashmapij.h>
    1908:   PetscErrorCode PetscHMapIJIterSet(PetscHMapIJ ht, PetscHashIter iter, PetscInt val)

    1910:   Input Parameters:
    1911: + ht   - The hash table
    1912: . iter - The iterator
    1913: - val  - The value

    1915:   Level: developer

    1917: .seealso: `PetscHMapIJPut()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
    1918: `PetscHMapIJSetWithMode()`
    1919: M*/

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

    1924:   Synopsis:
    1925: #include <petsc/private/hashmapij.h>
    1926:   PetscErrorCode PetscHMapIJIterDel(PetscHMapIJ ht, PetscHashIter iter)

    1928:   Input Parameters:
    1929: + ht   - The hash table
    1930: - iter - The iterator

    1932:   Level: developer

    1934: .seealso: `PetscHMapIJFind()`, `PetscHMapIJQueryDel()`, `PetscHMapIJDel()`
    1935: M*/

    1937: /*MC
    1938:   PetscHMapIJGetKeys - Get all keys from a hash table

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

    1944:   Input Parameters:
    1945: + ht    - The hash table
    1946: . off   - Input offset in array (usually zero)
    1947: - array - Array to put hash table keys in

    1949:   Output Parameters:
    1950: + off   - Output offset in array (output offset = input offset + hash table size)
    1951: - array - Array filled with the hash table keys

    1953:   Level: developer

    1955: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetVals()`
    1956: M*/

    1958: /*MC
    1959:   PetscHMapIJGetVals - Get all values from a hash table

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

    1965:   Input Parameters:
    1966: + ht    - The hash table
    1967: . off   - Input offset in array (usually zero)
    1968: - array - Array to put hash table values in

    1970:   Output Parameters:
    1971: + off   - Output offset in array (output offset = input offset + hash table size)
    1972: - array - Array filled with the hash table values

    1974:   Level: developer

    1976: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`
    1977: M*/

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

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

    1986:   Input Parameters:
    1987: + ht    - The hash table
    1988: . off   - Input offset in array (usually zero)
    1989: . karray - Array to put hash table keys in
    1990: - varray - Array to put hash table values in

    1992:   Output Parameters:
    1993: + off   - Output offset in array (output offset = input offset + hash table size)
    1994: . karray - Array filled with the hash table keys
    1995: - varray - Array filled with the hash table values

    1997:   Level: developer

    1999: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`, `PetscHMapIJGetVals()`
    2000: M*/
    2001: /* MANSEC = Sys */
    2002: /* SUBMANSEC = PetscH */

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

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

    2010:   Synopsis:
    2011:   typedef khash_t(HMapIJ) *PetscHMapIJ;

    2013:   Level: developer

    2015: .seealso: `PETSC_HASH_MAP()`, `PetscHMapIJCreate()`, `PETSC_HASH_SET()`, `PetscHSetIJCreate()`
    2016: S*/
    2017: typedef struct _PetscHashIJ PetscHMapIJ;

    2019: /*MC
    2020:   PetscHMapIJCreate - Create a hash table

    2022:   Synopsis:
    2023: #include <petsc/private/hashmapij.h>
    2024:   PetscErrorCode PetscHMapIJCreate(PetscHMapIJ *ht)

    2026:   Output Parameter:
    2027: . ht - The hash table

    2029:   Level: developer

    2031: .seealso: `PetscHMapIJCreateWithSize()`, `PetscHMapIJDestroy()`
    2032: M*/

    2034: /*MC
    2035:   PetscHMapIJCreateWithSize - Create a hash table with a given initial size

    2037:   Synopsis:
    2038: #include <petsc/private/hashmapij.h>
    2039:   PetscErrorCode PetscHMapIJCreateWithSize(PetscInt n, PetscHMapIJ *ht)

    2041:   Input Parameter:
    2042: . n - The size of the hash table

    2044:   Output Parameter:
    2045: . ht - The hash table

    2047:   Level: developer

    2049:   Note:
    2050:   `n` must be non-negative.

    2052: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJDestroy()`
    2053: M*/

    2055: /*MC
    2056:   PetscHMapIJDestroy - Destroy a hash table

    2058:   Synopsis:
    2059: #include <petsc/private/hashmapij.h>
    2060:   PetscErrorCode PetscHMapIJDestroy(PetscHMapIJ *ht)

    2062:   Input Parameter:
    2063: . ht - The hash table

    2065:   Level: developer

    2067: .seealso: `PetscHMapIJCreate()`, `PetscHMapIJCreateWithSize()`
    2068: M*/

    2070: /*MC
    2071:   PetscHMapIJReset - Reset a hash table

    2073:   Synopsis:
    2074: #include <petsc/private/hashmapij.h>
    2075:   PetscErrorCode PetscHMapIJReset(PetscHMapIJ ht)

    2077:   Input Parameter:
    2078: . ht - The hash table

    2080:   Level: developer

    2082: .seealso: `PetscHMapIJClear()`
    2083: M*/

    2085: /*MC
    2086:   PetscHMapIJDuplicate - Duplicate a hash table

    2088:   Synopsis:
    2089: #include <petsc/private/hashmapij.h>
    2090:   PetscErrorCode PetscHMapIJDuplicate(PetscHMapIJ ht, PetscHMapIJ *hd)

    2092:   Input Parameter:
    2093: . ht - The source hash table

    2095:   Output Parameter:
    2096: . ht - The duplicated hash table

    2098:   Level: developer

    2100: .seealso: `PetscHMapIJCreate()`
    2101: M*/

    2103: /*MC
    2104:   PetscHMapIJClear - Clear a hash table

    2106:   Synopsis:
    2107: #include <petsc/private/hashmapij.h>
    2108:   PetscErrorCode PetscHMapIJClear(PetscHMapIJ ht)

    2110:   Input Parameter:
    2111: . ht - The hash table

    2113:   Level: developer

    2115: .seealso: `PetscHMapIJReset()`
    2116: M*/

    2118: /*MC
    2119:   PetscHMapIJResize - Set the number of buckets in a hash table

    2121:   Synopsis:
    2122: #include <petsc/private/hashmapij.h>
    2123:   PetscErrorCode PetscHMapIJResize(PetscHMapIJ ht, PetscInt nb)

    2125:   Input Parameters:
    2126: + ht - The hash table
    2127: - nb - The number of buckets

    2129:   Level: developer

    2131: .seealso: `PetscHMapIJCreate()`
    2132: M*/

    2134: /*MC
    2135:   PetscHMapIJGetSize - Get the number of entries in a hash table

    2137:   Synopsis:
    2138: #include <petsc/private/hashmapij.h>
    2139:   PetscErrorCode PetscHMapIJGetSize(PetscHMapIJ ht, PetscInt *n)

    2141:   Input Parameter:
    2142: . ht - The hash table

    2144:   Output Parameter:
    2145: . n - The number of entries

    2147:   Level: developer

    2149: .seealso: `PetscHMapIJResize()`
    2150: M*/

    2152: /*MC
    2153:   PetscHMapIJGetCapacity - Get the current size of the array in the hash table

    2155:   Synopsis:
    2156: #include <petsc/private/hashmapij.h>
    2157:   PetscErrorCode PetscHMapIJGetCapacity(PetscHMapIJ ht, PetscInt *n)

    2159:   Input Parameter:
    2160: . ht - The hash table

    2162:   Output Parameter:
    2163: . n - The capacity

    2165:   Level: developer

    2167: .seealso: `PetscHMapIJResize()`, `PetscHMapIJGetSize()`
    2168: M*/

    2170: /*MC
    2171:   PetscHMapIJHas - Query for a key in the hash table

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

    2177:   Input Parameters:
    2178: + ht  - The hash table
    2179: - key - The key

    2181:   Output Parameter:
    2182: . has - Boolean indicating whether key is in the hash table

    2184:   Level: developer

    2186: .seealso: `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`, `PetscHMapIJSet()`,
    2187: `PetscHMapIJSetWithMode()`, `PetscHMapIJFind()`
    2188: M*/

    2190: /*MC
    2191:   PetscHMapIJGet - Get the value for a key in the hash table

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

    2197:   Input Parameters:
    2198: + ht  - The hash table
    2199: - key - The key

    2201:   Output Parameter:
    2202: . val - The value

    2204:   Level: developer

    2206: .seealso: `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`,
    2207: `PetscHMapIJGetWithDefault()`
    2208: M*/

    2210: /*MC
    2211:   PetscHMapIJGetWithDefault - Get the value for a key in the hash table but override the default
    2212:   value returned if the key was not found

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

    2218:   Input Parameters:
    2219: + ht          - The hash table
    2220: . key         - The key
    2221: - default_val - The default value to set `val` to if `key` was not found

    2223:   Output Parameter:
    2224: . val - The value

    2226:   Level: developer

    2228: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJIterGet()`
    2229: M*/

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

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

    2239:   Input Parameters:
    2240: + ht  - The hash table
    2241: . key - The key
    2242: - val - The value

    2244:   Level: developer

    2246: .seealso: `PetscHMapIJGet()`, `PetscHMapIJSetWithMode()`, `PetscHMapIJGetWithDefault()`,
    2247: `PetscHMapIJIterSet()`
    2248: M*/

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

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

    2257:   Input Parameters:
    2258: + ht   - The hash table
    2259: . key  - The key
    2260: . val  - The value
    2261: - mode - The insertion mode

    2263:   Level: developer

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

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

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

    2284: .seealso: `PetscHMapIJSet()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`,
    2285: `PetscHMapIJIterSet()`
    2286: M*/

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

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

    2295:   Input Parameters:
    2296: + ht  - The hash table
    2297: - key - The key

    2299:   Level: developer

    2301: .seealso: `PetscHMapIJHas()`, `PetscHMapIJIterDel()`
    2302: M*/

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

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

    2311:   Input Parameters:
    2312: + ht  - The hash table
    2313: . key - The key
    2314: - val - The value

    2316:   Output Parameter:
    2317: . missing - Boolean indicating whether the key was missing

    2319:   Level: developer

    2321: .seealso: `PetscHMapIJQueryDel()`, `PetscHMapIJSet()`, `PetscHMapIJSetWithMode()`
    2322: M*/

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

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

    2331:   Input Parameters:
    2332: + ht  - The hash table
    2333: - key - The key

    2335:   Output Parameter:
    2336: . present - Boolean indicating whether the key was present

    2338:   Level: developer

    2340: .seealso: `PetscHMapIJQuerySet()`, `PetscHMapIJDel()`
    2341: M*/

    2343: /*MC
    2344:   PetscHMapIJFind - Query for key in the hash table

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

    2350:   Input Parameters:
    2351: + ht  - The hash table
    2352: - key - The key

    2354:   Output Parameters:
    2355: + iter - Iterator referencing the value for key
    2356: - found - Boolean indicating whether the key was present

    2358:   Level: developer

    2360: .seealso: `PetscHMapIJIterGet()`, `PetscHMapIJIterDel()`
    2361: M*/

    2363: /*MC
    2364:   PetscHMapIJPut - Set a key in the hash table

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

    2370:   Input Parameters:
    2371: + ht  - The hash table
    2372: - key - The key

    2374:   Output Parameters:
    2375: + iter - Iterator referencing the value for key
    2376: - missing - Boolean indicating whether the key was missing

    2378:   Level: developer

    2380: .seealso: `PetscHMapIJIterSet()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
    2381: `PetscHMapIJSetWithMode()`
    2382: M*/

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

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

    2391:   Input Parameters:
    2392: + ht   - The hash table
    2393: - iter - The iterator

    2395:   Output Parameter:
    2396: . val  - The value

    2398:   Level: developer

    2400: .seealso: `PetscHMapIJFind()`, `PetscHMapIJGet()`, `PetscHMapIJGetWithDefault()`
    2401: M*/

    2403: /*MC
    2404:   PetscHMapIJIterSet - Set the value referenced by an iterator in the hash

    2406:   Synopsis:
    2407: #include <petsc/private/hashmapij.h>
    2408:   PetscErrorCode PetscHMapIJIterSet(PetscHMapIJ ht, PetscHashIter iter, PetscScalar val)

    2410:   Input Parameters:
    2411: + ht   - The hash table
    2412: . iter - The iterator
    2413: - val  - The value

    2415:   Level: developer

    2417: .seealso: `PetscHMapIJPut()`, `PetscHMapIJQuerySet()`, `PetscHMapIJSet()`,
    2418: `PetscHMapIJSetWithMode()`
    2419: M*/

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

    2424:   Synopsis:
    2425: #include <petsc/private/hashmapij.h>
    2426:   PetscErrorCode PetscHMapIJIterDel(PetscHMapIJ ht, PetscHashIter iter)

    2428:   Input Parameters:
    2429: + ht   - The hash table
    2430: - iter - The iterator

    2432:   Level: developer

    2434: .seealso: `PetscHMapIJFind()`, `PetscHMapIJQueryDel()`, `PetscHMapIJDel()`
    2435: M*/

    2437: /*MC
    2438:   PetscHMapIJGetKeys - Get all keys from a hash table

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

    2444:   Input Parameters:
    2445: + ht    - The hash table
    2446: . off   - Input offset in array (usually zero)
    2447: - array - Array to put hash table keys in

    2449:   Output Parameters:
    2450: + off   - Output offset in array (output offset = input offset + hash table size)
    2451: - array - Array filled with the hash table keys

    2453:   Level: developer

    2455: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetVals()`
    2456: M*/

    2458: /*MC
    2459:   PetscHMapIJGetVals - Get all values from a hash table

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

    2465:   Input Parameters:
    2466: + ht    - The hash table
    2467: . off   - Input offset in array (usually zero)
    2468: - array - Array to put hash table values in

    2470:   Output Parameters:
    2471: + off   - Output offset in array (output offset = input offset + hash table size)
    2472: - array - Array filled with the hash table values

    2474:   Level: developer

    2476: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`
    2477: M*/

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

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

    2486:   Input Parameters:
    2487: + ht    - The hash table
    2488: . off   - Input offset in array (usually zero)
    2489: . karray - Array to put hash table keys in
    2490: - varray - Array to put hash table values in

    2492:   Output Parameters:
    2493: + off   - Output offset in array (output offset = input offset + hash table size)
    2494: . karray - Array filled with the hash table keys
    2495: - varray - Array filled with the hash table values

    2497:   Level: developer

    2499: .seealso: `PetscHSetIJGetSize()`, `PetscHMapIJGetKeys()`, `PetscHMapIJGetVals()`
    2500: M*/
    2501: /* MANSEC = Sys */
    2502: /* SUBMANSEC = PetscH */

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

    2507: /*S
    2508:   PetscHMapIV - Hash table map with a key of PetscInt

    2510:   Synopsis:
    2511:   typedef khash_t(HMapIV) *PetscHMapIV;

    2513:   Level: developer

    2515: .seealso: `PETSC_HASH_MAP()`, `PetscHMapIVCreate()`, `PETSC_HASH_SET()`, `PetscHSetIVCreate()`
    2516: S*/
    2517: typedef struct _PetscHashIV PetscHMapIV;

    2519: /*MC
    2520:   PetscHMapIVCreate - Create a hash table

    2522:   Synopsis:
    2523: #include <petsc/private/hashmapiv.h>
    2524:   PetscErrorCode PetscHMapIVCreate(PetscHMapIV *ht)

    2526:   Output Parameter:
    2527: . ht - The hash table

    2529:   Level: developer

    2531: .seealso: `PetscHMapIVCreateWithSize()`, `PetscHMapIVDestroy()`
    2532: M*/

    2534: /*MC
    2535:   PetscHMapIVCreateWithSize - Create a hash table with a given initial size

    2537:   Synopsis:
    2538: #include <petsc/private/hashmapiv.h>
    2539:   PetscErrorCode PetscHMapIVCreateWithSize(PetscInt n, PetscHMapIV *ht)

    2541:   Input Parameter:
    2542: . n - The size of the hash table

    2544:   Output Parameter:
    2545: . ht - The hash table

    2547:   Level: developer

    2549:   Note:
    2550:   `n` must be non-negative.

    2552: .seealso: `PetscHMapIVCreate()`, `PetscHMapIVDestroy()`
    2553: M*/

    2555: /*MC
    2556:   PetscHMapIVDestroy - Destroy a hash table

    2558:   Synopsis:
    2559: #include <petsc/private/hashmapiv.h>
    2560:   PetscErrorCode PetscHMapIVDestroy(PetscHMapIV *ht)

    2562:   Input Parameter:
    2563: . ht - The hash table

    2565:   Level: developer

    2567: .seealso: `PetscHMapIVCreate()`, `PetscHMapIVCreateWithSize()`
    2568: M*/

    2570: /*MC
    2571:   PetscHMapIVReset - Reset a hash table

    2573:   Synopsis:
    2574: #include <petsc/private/hashmapiv.h>
    2575:   PetscErrorCode PetscHMapIVReset(PetscHMapIV ht)

    2577:   Input Parameter:
    2578: . ht - The hash table

    2580:   Level: developer

    2582: .seealso: `PetscHMapIVClear()`
    2583: M*/

    2585: /*MC
    2586:   PetscHMapIVDuplicate - Duplicate a hash table

    2588:   Synopsis:
    2589: #include <petsc/private/hashmapiv.h>
    2590:   PetscErrorCode PetscHMapIVDuplicate(PetscHMapIV ht, PetscHMapIV *hd)

    2592:   Input Parameter:
    2593: . ht - The source hash table

    2595:   Output Parameter:
    2596: . ht - The duplicated hash table

    2598:   Level: developer

    2600: .seealso: `PetscHMapIVCreate()`
    2601: M*/

    2603: /*MC
    2604:   PetscHMapIVClear - Clear a hash table

    2606:   Synopsis:
    2607: #include <petsc/private/hashmapiv.h>
    2608:   PetscErrorCode PetscHMapIVClear(PetscHMapIV ht)

    2610:   Input Parameter:
    2611: . ht - The hash table

    2613:   Level: developer

    2615: .seealso: `PetscHMapIVReset()`
    2616: M*/

    2618: /*MC
    2619:   PetscHMapIVResize - Set the number of buckets in a hash table

    2621:   Synopsis:
    2622: #include <petsc/private/hashmapiv.h>
    2623:   PetscErrorCode PetscHMapIVResize(PetscHMapIV ht, PetscInt nb)

    2625:   Input Parameters:
    2626: + ht - The hash table
    2627: - nb - The number of buckets

    2629:   Level: developer

    2631: .seealso: `PetscHMapIVCreate()`
    2632: M*/

    2634: /*MC
    2635:   PetscHMapIVGetSize - Get the number of entries in a hash table

    2637:   Synopsis:
    2638: #include <petsc/private/hashmapiv.h>
    2639:   PetscErrorCode PetscHMapIVGetSize(PetscHMapIV ht, PetscInt *n)

    2641:   Input Parameter:
    2642: . ht - The hash table

    2644:   Output Parameter:
    2645: . n - The number of entries

    2647:   Level: developer

    2649: .seealso: `PetscHMapIVResize()`
    2650: M*/

    2652: /*MC
    2653:   PetscHMapIVGetCapacity - Get the current size of the array in the hash table

    2655:   Synopsis:
    2656: #include <petsc/private/hashmapiv.h>
    2657:   PetscErrorCode PetscHMapIVGetCapacity(PetscHMapIV ht, PetscInt *n)

    2659:   Input Parameter:
    2660: . ht - The hash table

    2662:   Output Parameter:
    2663: . n - The capacity

    2665:   Level: developer

    2667: .seealso: `PetscHMapIVResize()`, `PetscHMapIVGetSize()`
    2668: M*/

    2670: /*MC
    2671:   PetscHMapIVHas - Query for a key in the hash table

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

    2677:   Input Parameters:
    2678: + ht  - The hash table
    2679: - key - The key

    2681:   Output Parameter:
    2682: . has - Boolean indicating whether key is in the hash table

    2684:   Level: developer

    2686: .seealso: `PetscHMapIVGet()`, `PetscHMapIVGetWithDefault()`, `PetscHMapIVSet()`,
    2687: `PetscHMapIVSetWithMode()`, `PetscHMapIVFind()`
    2688: M*/

    2690: /*MC
    2691:   PetscHMapIVGet - Get the value for a key in the hash table

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

    2697:   Input Parameters:
    2698: + ht  - The hash table
    2699: - key - The key

    2701:   Output Parameter:
    2702: . val - The value

    2704:   Level: developer

    2706: .seealso: `PetscHMapIVSet()`, `PetscHMapIVSetWithMode()`, `PetscHMapIVIterGet()`,
    2707: `PetscHMapIVGetWithDefault()`
    2708: M*/

    2710: /*MC
    2711:   PetscHMapIVGetWithDefault - Get the value for a key in the hash table but override the default
    2712:   value returned if the key was not found

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

    2718:   Input Parameters:
    2719: + ht          - The hash table
    2720: . key         - The key
    2721: - default_val - The default value to set `val` to if `key` was not found

    2723:   Output Parameter:
    2724: . val - The value

    2726:   Level: developer

    2728: .seealso: `PetscHMapIVGet()`, `PetscHMapIVSet()`, `PetscHMapIVSetWithMode()`, `PetscHMapIVIterGet()`
    2729: M*/

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

    2735:   Synopsis:
    2736: #include <petsc/private/hashmapiv.h>
    2737:   PetscErrorCode PetscHMapIVSet(PetscHMapIV ht, PetscInt key, PetscScalar val)

    2739:   Input Parameters:
    2740: + ht  - The hash table
    2741: . key - The key
    2742: - val - The value

    2744:   Level: developer

    2746: .seealso: `PetscHMapIVGet()`, `PetscHMapIVSetWithMode()`, `PetscHMapIVGetWithDefault()`,
    2747: `PetscHMapIVIterSet()`
    2748: M*/

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

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

    2757:   Input Parameters:
    2758: + ht   - The hash table
    2759: . key  - The key
    2760: . val  - The value
    2761: - mode - The insertion mode

    2763:   Level: developer

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

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

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

    2784: .seealso: `PetscHMapIVSet()`, `PetscHMapIVGet()`, `PetscHMapIVGetWithDefault()`,
    2785: `PetscHMapIVIterSet()`
    2786: M*/

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

    2791:   Synopsis:
    2792: #include <petsc/private/hashmapiv.h>
    2793:   PetscErrorCode PetscHMapIVDel(PetscHMapIV ht,PetscInt key)

    2795:   Input Parameters:
    2796: + ht  - The hash table
    2797: - key - The key

    2799:   Level: developer

    2801: .seealso: `PetscHMapIVHas()`, `PetscHMapIVIterDel()`
    2802: M*/

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

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

    2811:   Input Parameters:
    2812: + ht  - The hash table
    2813: . key - The key
    2814: - val - The value

    2816:   Output Parameter:
    2817: . missing - Boolean indicating whether the key was missing

    2819:   Level: developer

    2821: .seealso: `PetscHMapIVQueryDel()`, `PetscHMapIVSet()`, `PetscHMapIVSetWithMode()`
    2822: M*/

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

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

    2831:   Input Parameters:
    2832: + ht  - The hash table
    2833: - key - The key

    2835:   Output Parameter:
    2836: . present - Boolean indicating whether the key was present

    2838:   Level: developer

    2840: .seealso: `PetscHMapIVQuerySet()`, `PetscHMapIVDel()`
    2841: M*/

    2843: /*MC
    2844:   PetscHMapIVFind - Query for key in the hash table

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

    2850:   Input Parameters:
    2851: + ht  - The hash table
    2852: - key - The key

    2854:   Output Parameters:
    2855: + iter - Iterator referencing the value for key
    2856: - found - Boolean indicating whether the key was present

    2858:   Level: developer

    2860: .seealso: `PetscHMapIVIterGet()`, `PetscHMapIVIterDel()`
    2861: M*/

    2863: /*MC
    2864:   PetscHMapIVPut - Set a key in the hash table

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

    2870:   Input Parameters:
    2871: + ht  - The hash table
    2872: - key - The key

    2874:   Output Parameters:
    2875: + iter - Iterator referencing the value for key
    2876: - missing - Boolean indicating whether the key was missing

    2878:   Level: developer

    2880: .seealso: `PetscHMapIVIterSet()`, `PetscHMapIVQuerySet()`, `PetscHMapIVSet()`,
    2881: `PetscHMapIVSetWithMode()`
    2882: M*/

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

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

    2891:   Input Parameters:
    2892: + ht   - The hash table
    2893: - iter - The iterator

    2895:   Output Parameter:
    2896: . val  - The value

    2898:   Level: developer

    2900: .seealso: `PetscHMapIVFind()`, `PetscHMapIVGet()`, `PetscHMapIVGetWithDefault()`
    2901: M*/

    2903: /*MC
    2904:   PetscHMapIVIterSet - Set the value referenced by an iterator in the hash

    2906:   Synopsis:
    2907: #include <petsc/private/hashmapiv.h>
    2908:   PetscErrorCode PetscHMapIVIterSet(PetscHMapIV ht, PetscHashIter iter, PetscScalar val)

    2910:   Input Parameters:
    2911: + ht   - The hash table
    2912: . iter - The iterator
    2913: - val  - The value

    2915:   Level: developer

    2917: .seealso: `PetscHMapIVPut()`, `PetscHMapIVQuerySet()`, `PetscHMapIVSet()`,
    2918: `PetscHMapIVSetWithMode()`
    2919: M*/

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

    2924:   Synopsis:
    2925: #include <petsc/private/hashmapiv.h>
    2926:   PetscErrorCode PetscHMapIVIterDel(PetscHMapIV ht, PetscHashIter iter)

    2928:   Input Parameters:
    2929: + ht   - The hash table
    2930: - iter - The iterator

    2932:   Level: developer

    2934: .seealso: `PetscHMapIVFind()`, `PetscHMapIVQueryDel()`, `PetscHMapIVDel()`
    2935: M*/

    2937: /*MC
    2938:   PetscHMapIVGetKeys - Get all keys from a hash table

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

    2944:   Input Parameters:
    2945: + ht    - The hash table
    2946: . off   - Input offset in array (usually zero)
    2947: - array - Array to put hash table keys in

    2949:   Output Parameters:
    2950: + off   - Output offset in array (output offset = input offset + hash table size)
    2951: - array - Array filled with the hash table keys

    2953:   Level: developer

    2955: .seealso: `PetscHSetIVGetSize()`, `PetscHMapIVGetVals()`
    2956: M*/

    2958: /*MC
    2959:   PetscHMapIVGetVals - Get all values from a hash table

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

    2965:   Input Parameters:
    2966: + ht    - The hash table
    2967: . off   - Input offset in array (usually zero)
    2968: - array - Array to put hash table values in

    2970:   Output Parameters:
    2971: + off   - Output offset in array (output offset = input offset + hash table size)
    2972: - array - Array filled with the hash table values

    2974:   Level: developer

    2976: .seealso: `PetscHSetIVGetSize()`, `PetscHMapIVGetKeys()`
    2977: M*/

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

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

    2986:   Input Parameters:
    2987: + ht    - The hash table
    2988: . off   - Input offset in array (usually zero)
    2989: . karray - Array to put hash table keys in
    2990: - varray - Array to put hash table values in

    2992:   Output Parameters:
    2993: + off   - Output offset in array (output offset = input offset + hash table size)
    2994: . karray - Array filled with the hash table keys
    2995: - varray - Array filled with the hash table values

    2997:   Level: developer

    2999: .seealso: `PetscHSetIVGetSize()`, `PetscHMapIVGetKeys()`, `PetscHMapIVGetVals()`
    3000: M*/
    3001: /* MANSEC = Sys */
    3002: /* SUBMANSEC = PetscH */

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

    3007: /*S
    3008:   PetscHMapObj - Hash table map with a key of PetscInt64

    3010:   Synopsis:
    3011:   typedef khash_t(HMapObj) *PetscHMapObj;

    3013:   Level: developer

    3015: .seealso: `PETSC_HASH_MAP()`, `PetscHMapObjCreate()`, `PETSC_HASH_SET()`, `PetscHSetObjCreate()`
    3016: S*/
    3017: typedef struct _PetscHashObj PetscHMapObj;

    3019: /*MC
    3020:   PetscHMapObjCreate - Create a hash table

    3022:   Synopsis:
    3023: #include <petsc/private/hashmapobj.h>
    3024:   PetscErrorCode PetscHMapObjCreate(PetscHMapObj *ht)

    3026:   Output Parameter:
    3027: . ht - The hash table

    3029:   Level: developer

    3031: .seealso: `PetscHMapObjCreateWithSize()`, `PetscHMapObjDestroy()`
    3032: M*/

    3034: /*MC
    3035:   PetscHMapObjCreateWithSize - Create a hash table with a given initial size

    3037:   Synopsis:
    3038: #include <petsc/private/hashmapobj.h>
    3039:   PetscErrorCode PetscHMapObjCreateWithSize(PetscInt n, PetscHMapObj *ht)

    3041:   Input Parameter:
    3042: . n - The size of the hash table

    3044:   Output Parameter:
    3045: . ht - The hash table

    3047:   Level: developer

    3049:   Note:
    3050:   `n` must be non-negative.

    3052: .seealso: `PetscHMapObjCreate()`, `PetscHMapObjDestroy()`
    3053: M*/

    3055: /*MC
    3056:   PetscHMapObjDestroy - Destroy a hash table

    3058:   Synopsis:
    3059: #include <petsc/private/hashmapobj.h>
    3060:   PetscErrorCode PetscHMapObjDestroy(PetscHMapObj *ht)

    3062:   Input Parameter:
    3063: . ht - The hash table

    3065:   Level: developer

    3067: .seealso: `PetscHMapObjCreate()`, `PetscHMapObjCreateWithSize()`
    3068: M*/

    3070: /*MC
    3071:   PetscHMapObjReset - Reset a hash table

    3073:   Synopsis:
    3074: #include <petsc/private/hashmapobj.h>
    3075:   PetscErrorCode PetscHMapObjReset(PetscHMapObj ht)

    3077:   Input Parameter:
    3078: . ht - The hash table

    3080:   Level: developer

    3082: .seealso: `PetscHMapObjClear()`
    3083: M*/

    3085: /*MC
    3086:   PetscHMapObjDuplicate - Duplicate a hash table

    3088:   Synopsis:
    3089: #include <petsc/private/hashmapobj.h>
    3090:   PetscErrorCode PetscHMapObjDuplicate(PetscHMapObj ht, PetscHMapObj *hd)

    3092:   Input Parameter:
    3093: . ht - The source hash table

    3095:   Output Parameter:
    3096: . ht - The duplicated hash table

    3098:   Level: developer

    3100: .seealso: `PetscHMapObjCreate()`
    3101: M*/

    3103: /*MC
    3104:   PetscHMapObjClear - Clear a hash table

    3106:   Synopsis:
    3107: #include <petsc/private/hashmapobj.h>
    3108:   PetscErrorCode PetscHMapObjClear(PetscHMapObj ht)

    3110:   Input Parameter:
    3111: . ht - The hash table

    3113:   Level: developer

    3115: .seealso: `PetscHMapObjReset()`
    3116: M*/

    3118: /*MC
    3119:   PetscHMapObjResize - Set the number of buckets in a hash table

    3121:   Synopsis:
    3122: #include <petsc/private/hashmapobj.h>
    3123:   PetscErrorCode PetscHMapObjResize(PetscHMapObj ht, PetscInt nb)

    3125:   Input Parameters:
    3126: + ht - The hash table
    3127: - nb - The number of buckets

    3129:   Level: developer

    3131: .seealso: `PetscHMapObjCreate()`
    3132: M*/

    3134: /*MC
    3135:   PetscHMapObjGetSize - Get the number of entries in a hash table

    3137:   Synopsis:
    3138: #include <petsc/private/hashmapobj.h>
    3139:   PetscErrorCode PetscHMapObjGetSize(PetscHMapObj ht, PetscInt *n)

    3141:   Input Parameter:
    3142: . ht - The hash table

    3144:   Output Parameter:
    3145: . n - The number of entries

    3147:   Level: developer

    3149: .seealso: `PetscHMapObjResize()`
    3150: M*/

    3152: /*MC
    3153:   PetscHMapObjGetCapacity - Get the current size of the array in the hash table

    3155:   Synopsis:
    3156: #include <petsc/private/hashmapobj.h>
    3157:   PetscErrorCode PetscHMapObjGetCapacity(PetscHMapObj ht, PetscInt *n)

    3159:   Input Parameter:
    3160: . ht - The hash table

    3162:   Output Parameter:
    3163: . n - The capacity

    3165:   Level: developer

    3167: .seealso: `PetscHMapObjResize()`, `PetscHMapObjGetSize()`
    3168: M*/

    3170: /*MC
    3171:   PetscHMapObjHas - Query for a key in the hash table

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

    3177:   Input Parameters:
    3178: + ht  - The hash table
    3179: - key - The key

    3181:   Output Parameter:
    3182: . has - Boolean indicating whether key is in the hash table

    3184:   Level: developer

    3186: .seealso: `PetscHMapObjGet()`, `PetscHMapObjGetWithDefault()`, `PetscHMapObjSet()`,
    3187: `PetscHMapObjSetWithMode()`, `PetscHMapObjFind()`
    3188: M*/

    3190: /*MC
    3191:   PetscHMapObjGet - Get the value for a key in the hash table

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

    3197:   Input Parameters:
    3198: + ht  - The hash table
    3199: - key - The key

    3201:   Output Parameter:
    3202: . val - The value

    3204:   Level: developer

    3206: .seealso: `PetscHMapObjSet()`, `PetscHMapObjSetWithMode()`, `PetscHMapObjIterGet()`,
    3207: `PetscHMapObjGetWithDefault()`
    3208: M*/

    3210: /*MC
    3211:   PetscHMapObjGetWithDefault - Get the value for a key in the hash table but override the default
    3212:   value returned if the key was not found

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

    3218:   Input Parameters:
    3219: + ht          - The hash table
    3220: . key         - The key
    3221: - default_val - The default value to set `val` to if `key` was not found

    3223:   Output Parameter:
    3224: . val - The value

    3226:   Level: developer

    3228: .seealso: `PetscHMapObjGet()`, `PetscHMapObjSet()`, `PetscHMapObjSetWithMode()`, `PetscHMapObjIterGet()`
    3229: M*/

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

    3235:   Synopsis:
    3236: #include <petsc/private/hashmapobj.h>
    3237:   PetscErrorCode PetscHMapObjSet(PetscHMapObj ht, PetscInt64 key, PetscObject val)

    3239:   Input Parameters:
    3240: + ht  - The hash table
    3241: . key - The key
    3242: - val - The value

    3244:   Level: developer

    3246: .seealso: `PetscHMapObjGet()`, `PetscHMapObjSetWithMode()`, `PetscHMapObjGetWithDefault()`,
    3247: `PetscHMapObjIterSet()`
    3248: M*/

    3250: /*MC
    3251:   PetscHMapObjSetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode`

    3253:   Synopsis:
    3254: #include <petsc/private/hashmapobj.h>
    3255:   PetscErrorCode PetscHMapObjSetWithMode(PetscHMapObj ht, PetscInt64 key, PetscObject val, InsertMode mode)

    3257:   Input Parameters:
    3258: + ht   - The hash table
    3259: . key  - The key
    3260: . val  - The value
    3261: - mode - The insertion mode

    3263:   Level: developer

    3265:   Notes:
    3266:   `mode` may be any of the following\:
    3267:   - `INSERT_VALUES`\: this routine behaves identically to `PetscHMapObjSet()`.
    3268:   - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`)
    3269:                    is inserted into `ht` as-if-by `INSERT_VALUES`.
    3270:   - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the
    3271:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
    3272:                    `INSERT_VALUES`.
    3273:   - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the
    3274:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
    3275:                    `INSERT_VALUES`.

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

    3279:    Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type
    3280:    it is not available by default for all PETSc hash table instantiations. If a particular
    3281:    instantiation supports this routine it must define `PETSC_HMAPObj_HAVE_EXTENDED_API` to
    3282:    `1`.

    3284: .seealso: `PetscHMapObjSet()`, `PetscHMapObjGet()`, `PetscHMapObjGetWithDefault()`,
    3285: `PetscHMapObjIterSet()`
    3286: M*/

    3288: /*MC
    3289:   PetscHMapObjDel - Remove a key and its value from the hash table

    3291:   Synopsis:
    3292: #include <petsc/private/hashmapobj.h>
    3293:   PetscErrorCode PetscHMapObjDel(PetscHMapObj ht,PetscInt64 key)

    3295:   Input Parameters:
    3296: + ht  - The hash table
    3297: - key - The key

    3299:   Level: developer

    3301: .seealso: `PetscHMapObjHas()`, `PetscHMapObjIterDel()`
    3302: M*/

    3304: /*MC
    3305:   PetscHMapObjQuerySet - Query and set a (key,value) entry in the hash table

    3307:   Synopsis:
    3308: #include <petsc/private/hashmapobj.h>
    3309:   PetscErrorCode PetscHMapObjQuerySet(PetscHMapObj ht, PetscInt64 key, PetscObject val, PetscBool *missing)

    3311:   Input Parameters:
    3312: + ht  - The hash table
    3313: . key - The key
    3314: - val - The value

    3316:   Output Parameter:
    3317: . missing - Boolean indicating whether the key was missing

    3319:   Level: developer

    3321: .seealso: `PetscHMapObjQueryDel()`, `PetscHMapObjSet()`, `PetscHMapObjSetWithMode()`
    3322: M*/

    3324: /*MC
    3325:   PetscHMapObjQueryDel - Query and remove a (key,value) entry from the hash table

    3327:   Synopsis:
    3328: #include <petsc/private/hashmapobj.h>
    3329:   PetscErrorCode PetscHMapObjQueryDel(PetscHMapObj ht, PetscInt64 key, PetscBool *present)

    3331:   Input Parameters:
    3332: + ht  - The hash table
    3333: - key - The key

    3335:   Output Parameter:
    3336: . present - Boolean indicating whether the key was present

    3338:   Level: developer

    3340: .seealso: `PetscHMapObjQuerySet()`, `PetscHMapObjDel()`
    3341: M*/

    3343: /*MC
    3344:   PetscHMapObjFind - Query for key in the hash table

    3346:   Synopsis:
    3347: #include <petsc/private/hashmapobj.h>
    3348:   PetscErrorCode PetscHMapObjFind(PetscHMapObj ht, PetscInt64 key, PetscHashIter *iter, PetscBool *found)

    3350:   Input Parameters:
    3351: + ht  - The hash table
    3352: - key - The key

    3354:   Output Parameters:
    3355: + iter - Iterator referencing the value for key
    3356: - found - Boolean indicating whether the key was present

    3358:   Level: developer

    3360: .seealso: `PetscHMapObjIterGet()`, `PetscHMapObjIterDel()`
    3361: M*/

    3363: /*MC
    3364:   PetscHMapObjPut - Set a key in the hash table

    3366:   Synopsis:
    3367: #include <petsc/private/hashmapobj.h>
    3368:   PetscErrorCode PetscHMapObjPut(PetscHMapObj ht, PetscInt64 key, PetscHashIter *iter, PetscBool *missing)

    3370:   Input Parameters:
    3371: + ht  - The hash table
    3372: - key - The key

    3374:   Output Parameters:
    3375: + iter - Iterator referencing the value for key
    3376: - missing - Boolean indicating whether the key was missing

    3378:   Level: developer

    3380: .seealso: `PetscHMapObjIterSet()`, `PetscHMapObjQuerySet()`, `PetscHMapObjSet()`,
    3381: `PetscHMapObjSetWithMode()`
    3382: M*/

    3384: /*MC
    3385:   PetscHMapObjIterGet - Get the value referenced by an iterator in the hash table

    3387:   Synopsis:
    3388: #include <petsc/private/hashmapobj.h>
    3389:   PetscErrorCode PetscHMapObjIterGet(PetscHMapObj ht, PetscHashIter iter, PetscObject *val)

    3391:   Input Parameters:
    3392: + ht   - The hash table
    3393: - iter - The iterator

    3395:   Output Parameter:
    3396: . val  - The value

    3398:   Level: developer

    3400: .seealso: `PetscHMapObjFind()`, `PetscHMapObjGet()`, `PetscHMapObjGetWithDefault()`
    3401: M*/

    3403: /*MC
    3404:   PetscHMapObjIterSet - Set the value referenced by an iterator in the hash

    3406:   Synopsis:
    3407: #include <petsc/private/hashmapobj.h>
    3408:   PetscErrorCode PetscHMapObjIterSet(PetscHMapObj ht, PetscHashIter iter, PetscObject val)

    3410:   Input Parameters:
    3411: + ht   - The hash table
    3412: . iter - The iterator
    3413: - val  - The value

    3415:   Level: developer

    3417: .seealso: `PetscHMapObjPut()`, `PetscHMapObjQuerySet()`, `PetscHMapObjSet()`,
    3418: `PetscHMapObjSetWithMode()`
    3419: M*/

    3421: /*MC
    3422:   PetscHMapObjIterDel - Remove the (key,value) referenced by an iterator from the hash table

    3424:   Synopsis:
    3425: #include <petsc/private/hashmapobj.h>
    3426:   PetscErrorCode PetscHMapObjIterDel(PetscHMapObj ht, PetscHashIter iter)

    3428:   Input Parameters:
    3429: + ht   - The hash table
    3430: - iter - The iterator

    3432:   Level: developer

    3434: .seealso: `PetscHMapObjFind()`, `PetscHMapObjQueryDel()`, `PetscHMapObjDel()`
    3435: M*/

    3437: /*MC
    3438:   PetscHMapObjGetKeys - Get all keys from a hash table

    3440:   Synopsis:
    3441: #include <petsc/private/hashmapobj.h>
    3442:   PetscErrorCode PetscHMapObjGetKeys(PetscHMapObj ht, PetscInt *off, PetscInt64 array[])

    3444:   Input Parameters:
    3445: + ht    - The hash table
    3446: . off   - Input offset in array (usually zero)
    3447: - array - Array to put hash table keys in

    3449:   Output Parameters:
    3450: + off   - Output offset in array (output offset = input offset + hash table size)
    3451: - array - Array filled with the hash table keys

    3453:   Level: developer

    3455: .seealso: `PetscHSetObjGetSize()`, `PetscHMapObjGetVals()`
    3456: M*/

    3458: /*MC
    3459:   PetscHMapObjGetVals - Get all values from a hash table

    3461:   Synopsis:
    3462: #include <petsc/private/hashmapobj.h>
    3463:   PetscErrorCode PetscHMapObjGetVals(PetscHMapObj ht, PetscInt *off, PetscObject array[])

    3465:   Input Parameters:
    3466: + ht    - The hash table
    3467: . off   - Input offset in array (usually zero)
    3468: - array - Array to put hash table values in

    3470:   Output Parameters:
    3471: + off   - Output offset in array (output offset = input offset + hash table size)
    3472: - array - Array filled with the hash table values

    3474:   Level: developer

    3476: .seealso: `PetscHSetObjGetSize()`, `PetscHMapObjGetKeys()`
    3477: M*/

    3479: /*MC
    3480:   PetscHMapObjGetPairs - Get all (key,value) pairs from a hash table

    3482:   Synopsis:
    3483: #include <petsc/private/hashmapobj.h>
    3484:   PetscErrorCode PetscHMapObjGetPairs(PetscHMapObj ht, PetscInt *off, PetscInt64 karray[], PetscObject varray[])

    3486:   Input Parameters:
    3487: + ht    - The hash table
    3488: . off   - Input offset in array (usually zero)
    3489: . karray - Array to put hash table keys in
    3490: - varray - Array to put hash table values in

    3492:   Output Parameters:
    3493: + off   - Output offset in array (output offset = input offset + hash table size)
    3494: . karray - Array filled with the hash table keys
    3495: - varray - Array filled with the hash table values

    3497:   Level: developer

    3499: .seealso: `PetscHSetObjGetSize()`, `PetscHMapObjGetKeys()`, `PetscHMapObjGetVals()`
    3500: M*/