Actual source code: hashmap.txt.h

      1: /* SUBMANSEC = PetscH */

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

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

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

     12:   Level: developer

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

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

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

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

     28:   Level: developer

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

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

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

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

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

     46:   Level: developer

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

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

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

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

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

     64:   Level: developer

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

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

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

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

     79:   Level: developer

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

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

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

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

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

     97:   Level: developer

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

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

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

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

    112:   Level: developer

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

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

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

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

    128:   Level: developer

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

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

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

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

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

    146:   Level: developer

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

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

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

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

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

    164:   Level: developer

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

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

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

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

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

    183:   Level: developer

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

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

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

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

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

    203:   Level: developer

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

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

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

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

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

    225:   Level: developer

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

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

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

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

    243:   Level: developer

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

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

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

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

    262:   Level: developer

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

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

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

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

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

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

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

    298:   Level: developer

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

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

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

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

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

    318:   Level: developer

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

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

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

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

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

    337:   Level: developer

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

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

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

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

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

    357:   Level: developer

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

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

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

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

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

    377:   Level: developer

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

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

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

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

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

    397:   Level: developer

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

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

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

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

    414:   Level: developer

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

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

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

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

    431:   Level: developer

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

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

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

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

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

    452:   Level: developer

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

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

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

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

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

    473:   Level: developer

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

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

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

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

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

    496:   Level: developer

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

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

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

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

    511:   Level: developer

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

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

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

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

    527:   Level: developer

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

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

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

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

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

    545:   Level: developer

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

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

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

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

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

    563:   Level: developer

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

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

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

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

    578:   Level: developer

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

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

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

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

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

    596:   Level: developer

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

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

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

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

    611:   Level: developer

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

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

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

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

    627:   Level: developer

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

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

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

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

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

    645:   Level: developer

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

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

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

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

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

    663:   Level: developer

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

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

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

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

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

    682:   Level: developer

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

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

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

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

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

    702:   Level: developer

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

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

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

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

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

    724:   Level: developer

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

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

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

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

    742:   Level: developer

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

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

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

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

    761:   Level: developer

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

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

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

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

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

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

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

    797:   Level: developer

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

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

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

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

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

    817:   Level: developer

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

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

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

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

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

    836:   Level: developer

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

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

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

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

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

    856:   Level: developer

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

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

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

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

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

    876:   Level: developer

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

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

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

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

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

    896:   Level: developer

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

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

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

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

    913:   Level: developer

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

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

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

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

    930:   Level: developer

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

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

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

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

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

    951:   Level: developer

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

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

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

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

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

    972:   Level: developer

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

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

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

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

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

    995:   Level: developer

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

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

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

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

    1010:   Level: developer

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

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

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

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

    1026:   Level: developer

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

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

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

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

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

    1044:   Level: developer

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

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

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

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

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

    1062:   Level: developer

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

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

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

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

    1077:   Level: developer

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

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

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

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

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

    1095:   Level: developer

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

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

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

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

    1110:   Level: developer

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

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

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

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

    1126:   Level: developer

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

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

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

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

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

    1144:   Level: developer

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

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

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

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

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

    1162:   Level: developer

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

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

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

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

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

    1181:   Level: developer

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

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

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

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

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

    1201:   Level: developer

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

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

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

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

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

    1223:   Level: developer

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

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

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

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

    1241:   Level: developer

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

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

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

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

    1260:   Level: developer

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

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

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

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

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

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

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

    1296:   Level: developer

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

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

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

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

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

    1316:   Level: developer

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

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

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

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

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

    1335:   Level: developer

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

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

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

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

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

    1355:   Level: developer

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

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

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

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

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

    1375:   Level: developer

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

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

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

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

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

    1395:   Level: developer

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

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

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

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

    1412:   Level: developer

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

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

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

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

    1429:   Level: developer

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

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

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

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

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

    1450:   Level: developer

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

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

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

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

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

    1471:   Level: developer

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

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

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

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

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

    1494:   Level: developer

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

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

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

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

    1509:   Level: developer

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

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

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

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

    1525:   Level: developer

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

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

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

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

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

    1543:   Level: developer

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

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

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

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

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

    1561:   Level: developer

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

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

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

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

    1576:   Level: developer

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

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

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

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

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

    1594:   Level: developer

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

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

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

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

    1609:   Level: developer

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

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

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

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

    1625:   Level: developer

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

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

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

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

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

    1643:   Level: developer

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

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

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

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

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

    1661:   Level: developer

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

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

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

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

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

    1680:   Level: developer

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

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

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

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

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

    1700:   Level: developer

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

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

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

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

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

    1722:   Level: developer

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

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

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

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

    1740:   Level: developer

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

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

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

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

    1759:   Level: developer

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

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

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

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

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

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

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

    1795:   Level: developer

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

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

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

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

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

    1815:   Level: developer

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

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

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

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

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

    1834:   Level: developer

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

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

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

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

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

    1854:   Level: developer

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

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

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

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

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

    1874:   Level: developer

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

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

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

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

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

    1894:   Level: developer

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

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

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

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

    1911:   Level: developer

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

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

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

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

    1928:   Level: developer

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

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

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

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

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

    1949:   Level: developer

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

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

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

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

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

    1970:   Level: developer

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

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

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

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

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

    1993:   Level: developer

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

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

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

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

    2008:   Level: developer

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

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

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

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

    2024:   Level: developer

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

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

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

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

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

    2042:   Level: developer

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

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

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

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

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

    2060:   Level: developer

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

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

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

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

    2075:   Level: developer

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

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

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

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

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

    2093:   Level: developer

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

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

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

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

    2108:   Level: developer

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

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

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

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

    2124:   Level: developer

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

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

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

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

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

    2142:   Level: developer

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

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

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

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

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

    2160:   Level: developer

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

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

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

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

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

    2179:   Level: developer

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

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

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

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

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

    2199:   Level: developer

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

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

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

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

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

    2221:   Level: developer

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

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

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

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

    2239:   Level: developer

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

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

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

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

    2258:   Level: developer

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

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

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

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

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

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

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

    2294:   Level: developer

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

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

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

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

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

    2314:   Level: developer

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

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

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

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

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

    2333:   Level: developer

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

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

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

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

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

    2353:   Level: developer

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

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

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

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

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

    2373:   Level: developer

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

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

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

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

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

    2393:   Level: developer

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

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

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

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

    2410:   Level: developer

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

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

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

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

    2427:   Level: developer

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

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

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

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

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

    2448:   Level: developer

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

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

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

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

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

    2469:   Level: developer

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

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

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

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

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

    2492:   Level: developer

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

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

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

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

    2507:   Level: developer

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

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

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

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

    2523:   Level: developer

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

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

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

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

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

    2541:   Level: developer

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

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

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

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

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

    2559:   Level: developer

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

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

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

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

    2574:   Level: developer

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

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

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

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

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

    2592:   Level: developer

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

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

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

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

    2607:   Level: developer

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

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

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

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

    2623:   Level: developer

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

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

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

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

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

    2641:   Level: developer

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

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

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

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

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

    2659:   Level: developer

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

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

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

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

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

    2678:   Level: developer

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

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

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

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

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

    2698:   Level: developer

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

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

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

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

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

    2720:   Level: developer

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

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

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

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

    2738:   Level: developer

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

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

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

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

    2757:   Level: developer

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

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

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

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

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

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

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

    2793:   Level: developer

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

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

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

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

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

    2813:   Level: developer

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

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

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

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

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

    2832:   Level: developer

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

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

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

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

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

    2852:   Level: developer

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

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

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

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

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

    2872:   Level: developer

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

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

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

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

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

    2892:   Level: developer

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

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

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

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

    2909:   Level: developer

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

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

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

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

    2926:   Level: developer

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

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

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

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

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

    2947:   Level: developer

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

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

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

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

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

    2968:   Level: developer

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

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

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

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

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

    2991:   Level: developer

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

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

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

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

    3006:   Level: developer

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

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

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

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

    3022:   Level: developer

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

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

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

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

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

    3040:   Level: developer

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

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

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

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

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

    3058:   Level: developer

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

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

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

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

    3073:   Level: developer

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

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

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

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

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

    3091:   Level: developer

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

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

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

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

    3106:   Level: developer

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

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

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

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

    3122:   Level: developer

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

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

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

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

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

    3140:   Level: developer

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

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

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

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

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

    3158:   Level: developer

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

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

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

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

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

    3177:   Level: developer

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

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

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

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

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

    3197:   Level: developer

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

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

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

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

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

    3219:   Level: developer

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

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

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

    3232:   Input Parameters:
    3233: + ht  - The hash table
    3234: . key - The key
    3235: - val - The value

    3237:   Level: developer

    3239: .seealso: `PetscHMapObjGet()`, `PetscHMapObjSetWithMode()`, `PetscHMapObjGetWithDefault()`,
    3240: `PetscHMapObjIterSet()`
    3241: M*/

    3243: /*MC
    3244:   PetscHMapObjSetWithMode - Set a (key,value) entry in the hash table according to an `InsertMode`

    3246:   Synopsis:
    3247: #include <petsc/private/hashmapobj.h>
    3248:   PetscErrorCode PetscHMapObjSetWithMode(PetscHMapObj ht, PetscInt64 key, PetscObject val, InsertMode mode)

    3250:   Input Parameters:
    3251: + ht   - The hash table
    3252: . key  - The key
    3253: . val  - The value
    3254: - mode - The insertion mode

    3256:   Level: developer

    3258:   Notes:
    3259:   `mode` may be any of the following\:
    3260:   - `INSERT_VALUES`\: this routine behaves identically to `PetscHMapObjSet()`.
    3261:   - `ADD_VALUES`\: if `key` is found `val` is added to the current entry, otherwise (`key`, `value`)
    3262:                    is inserted into `ht` as-if-by `INSERT_VALUES`.
    3263:   - `MAX_VALUES`\: if `key` is found the current value is replaced by the maximum of `val` and the
    3264:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
    3265:                    `INSERT_VALUES`.
    3266:   - `MIN_VALUES`\: if `key` is found the current value is replaced by the minimum of `val` and the
    3267:                    current entry, otherwise (`key`, `value`) is inserted into `ht` as-if-by
    3268:                    `INSERT_VALUES`.

    3270:    All other `InsertMode` values raise an error.

    3272:    Since this routine relies on `+`, `<`, and `>` being well-formed for a particular type
    3273:    it is not available by default for all PETSc hash table instantiations. If a particular
    3274:    instantiation supports this routine it must define `PETSC_HMAPObj_HAVE_EXTENDED_API` to
    3275:    `1`.

    3277: .seealso: `PetscHMapObjSet()`, `PetscHMapObjGet()`, `PetscHMapObjGetWithDefault()`,
    3278: `PetscHMapObjIterSet()`
    3279: M*/

    3281: /*MC
    3282:   PetscHMapObjDel - Remove a key and its value from the hash table

    3284:   Synopsis:
    3285: #include <petsc/private/hashmapobj.h>
    3286:   PetscErrorCode PetscHMapObjDel(PetscHMapObj ht,PetscInt64 key)

    3288:   Input Parameters:
    3289: + ht  - The hash table
    3290: - key - The key

    3292:   Level: developer

    3294: .seealso: `PetscHMapObjHas()`, `PetscHMapObjIterDel()`
    3295: M*/

    3297: /*MC
    3298:   PetscHMapObjQuerySet - Query and set a (key,value) entry in the hash table

    3300:   Synopsis:
    3301: #include <petsc/private/hashmapobj.h>
    3302:   PetscErrorCode PetscHMapObjQuerySet(PetscHMapObj ht, PetscInt64 key, PetscObject val, PetscBool *missing)

    3304:   Input Parameters:
    3305: + ht  - The hash table
    3306: . key - The key
    3307: - val - The value

    3309:   Output Parameter:
    3310: . missing - Boolean indicating whether the key was missing

    3312:   Level: developer

    3314: .seealso: `PetscHMapObjQueryDel()`, `PetscHMapObjSet()`, `PetscHMapObjSetWithMode()`
    3315: M*/

    3317: /*MC
    3318:   PetscHMapObjQueryDel - Query and remove a (key,value) entry from the hash table

    3320:   Synopsis:
    3321: #include <petsc/private/hashmapobj.h>
    3322:   PetscErrorCode PetscHMapObjQueryDel(PetscHMapObj ht, PetscInt64 key, PetscBool *present)

    3324:   Input Parameters:
    3325: + ht  - The hash table
    3326: - key - The key

    3328:   Output Parameter:
    3329: . present - Boolean indicating whether the key was present

    3331:   Level: developer

    3333: .seealso: `PetscHMapObjQuerySet()`, `PetscHMapObjDel()`
    3334: M*/

    3336: /*MC
    3337:   PetscHMapObjFind - Query for key in the hash table

    3339:   Synopsis:
    3340: #include <petsc/private/hashmapobj.h>
    3341:   PetscErrorCode PetscHMapObjFind(PetscHMapObj ht, PetscInt64 key, PetscHashIter *iter, PetscBool *found)

    3343:   Input Parameters:
    3344: + ht  - The hash table
    3345: - key - The key

    3347:   Output Parameters:
    3348: + iter - Iterator referencing the value for key
    3349: - found - Boolean indicating whether the key was present

    3351:   Level: developer

    3353: .seealso: `PetscHMapObjIterGet()`, `PetscHMapObjIterDel()`
    3354: M*/

    3356: /*MC
    3357:   PetscHMapObjPut - Set a key in the hash table

    3359:   Synopsis:
    3360: #include <petsc/private/hashmapobj.h>
    3361:   PetscErrorCode PetscHMapObjPut(PetscHMapObj ht, PetscInt64 key, PetscHashIter *iter, PetscBool *missing)

    3363:   Input Parameters:
    3364: + ht  - The hash table
    3365: - key - The key

    3367:   Output Parameters:
    3368: + iter - Iterator referencing the value for key
    3369: - missing - Boolean indicating whether the key was missing

    3371:   Level: developer

    3373: .seealso: `PetscHMapObjIterSet()`, `PetscHMapObjQuerySet()`, `PetscHMapObjSet()`,
    3374: `PetscHMapObjSetWithMode()`
    3375: M*/

    3377: /*MC
    3378:   PetscHMapObjIterGet - Get the value referenced by an iterator in the hash table

    3380:   Synopsis:
    3381: #include <petsc/private/hashmapobj.h>
    3382:   PetscErrorCode PetscHMapObjIterGet(PetscHMapObj ht, PetscHashIter iter, PetscObject *val)

    3384:   Input Parameters:
    3385: + ht   - The hash table
    3386: - iter - The iterator

    3388:   Output Parameter:
    3389: . val  - The value

    3391:   Level: developer

    3393: .seealso: `PetscHMapObjFind()`, `PetscHMapObjGet()`, `PetscHMapObjGetWithDefault()`
    3394: M*/

    3396: /*MC
    3397:   PetscHMapObjIterSet - Set the value referenced by an iterator in the hash

    3399:   Synopsis:
    3400: #include <petsc/private/hashmapobj.h>
    3401:   PetscErrorCode PetscHMapObjIterSet(PetscHMapObj ht, PetscHashIter iter, PetscObject val)

    3403:   Input Parameters:
    3404: + ht   - The hash table
    3405: . iter - The iterator
    3406: - val  - The value

    3408:   Level: developer

    3410: .seealso: `PetscHMapObjPut()`, `PetscHMapObjQuerySet()`, `PetscHMapObjSet()`,
    3411: `PetscHMapObjSetWithMode()`
    3412: M*/

    3414: /*MC
    3415:   PetscHMapObjIterDel - Remove the (key,value) referenced by an iterator from the hash table

    3417:   Synopsis:
    3418: #include <petsc/private/hashmapobj.h>
    3419:   PetscErrorCode PetscHMapObjIterDel(PetscHMapObj ht, PetscHashIter iter)

    3421:   Input Parameters:
    3422: + ht   - The hash table
    3423: - iter - The iterator

    3425:   Level: developer

    3427: .seealso: `PetscHMapObjFind()`, `PetscHMapObjQueryDel()`, `PetscHMapObjDel()`
    3428: M*/

    3430: /*MC
    3431:   PetscHMapObjGetKeys - Get all keys from a hash table

    3433:   Synopsis:
    3434: #include <petsc/private/hashmapobj.h>
    3435:   PetscErrorCode PetscHMapObjGetKeys(PetscHMapObj ht, PetscInt *off, PetscInt64 array[])

    3437:   Input Parameters:
    3438: + ht    - The hash table
    3439: . off   - Input offset in array (usually zero)
    3440: - array - Array to put hash table keys in

    3442:   Output Parameters:
    3443: + off   - Output offset in array (output offset = input offset + hash table size)
    3444: - array - Array filled with the hash table keys

    3446:   Level: developer

    3448: .seealso: `PetscHSetObjGetSize()`, `PetscHMapObjGetVals()`
    3449: M*/

    3451: /*MC
    3452:   PetscHMapObjGetVals - Get all values from a hash table

    3454:   Synopsis:
    3455: #include <petsc/private/hashmapobj.h>
    3456:   PetscErrorCode PetscHMapObjGetVals(PetscHMapObj ht, PetscInt *off, PetscObject array[])

    3458:   Input Parameters:
    3459: + ht    - The hash table
    3460: . off   - Input offset in array (usually zero)
    3461: - array - Array to put hash table values in

    3463:   Output Parameters:
    3464: + off   - Output offset in array (output offset = input offset + hash table size)
    3465: - array - Array filled with the hash table values

    3467:   Level: developer

    3469: .seealso: `PetscHSetObjGetSize()`, `PetscHMapObjGetKeys()`
    3470: M*/

    3472: /*MC
    3473:   PetscHMapObjGetPairs - Get all (key,value) pairs from a hash table

    3475:   Synopsis:
    3476: #include <petsc/private/hashmapobj.h>
    3477:   PetscErrorCode PetscHMapObjGetPairs(PetscHMapObj ht, PetscInt *off, PetscInt64 karray[], PetscObject varray[])

    3479:   Input Parameters:
    3480: + ht    - The hash table
    3481: . off   - Input offset in array (usually zero)
    3482: . karray - Array to put hash table keys in
    3483: - varray - Array to put hash table values in

    3485:   Output Parameters:
    3486: + off   - Output offset in array (output offset = input offset + hash table size)
    3487: . karray - Array filled with the hash table keys
    3488: - varray - Array filled with the hash table values

    3490:   Level: developer

    3492: .seealso: `PetscHSetObjGetSize()`, `PetscHMapObjGetKeys()`, `PetscHMapObjGetVals()`
    3493: M*/