Actual source code: prefix.c
petsc-3.13.6 2020-09-29
Report Typos and Errors

      2: /*
      3:      Provides utility routines for manulating any type of PETSc object.
      4: */
      5:  #include <petsc/private/petscimpl.h>

      7: /*@C
      8:    PetscObjectGetOptions - Gets the options database used by the object. Call immediately after creating the object.

     10:    Collective on PetscObject

     12:    Input Parameter:
     13: .  obj - any PETSc object, for example a Vec, Mat or KSP.

     15:    Output Parameter:
     16: .  options - the options database

     18:    Notes:
     19:     if this is not called the object will use the default options database

     21:   Level: advanced

     23: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
     24:           PetscObjectGetOptionsPrefix(), PetscObjectSetOptions()

     26: @*/
     27: PetscErrorCode  PetscObjectGetOptions(PetscObject obj,PetscOptions *options)
     28: {
     31:   *options = obj->options;
     32:   return(0);
     33: }

     35: /*@C
     36:    PetscObjectSetOptions - Sets the options database used by the object. Call immediately after creating the object.

     38:    Collective on PetscObject

     40:    Input Parameters:
     41: +  obj - any PETSc object, for example a Vec, Mat or KSP.
     42: -  options - the options database, use NULL for default

     44:    Notes:
     45:     if this is not called the object will use the default options database

     47:   Level: advanced

     49: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
     50:           PetscObjectGetOptionsPrefix(), PetscObjectGetOptions()

     52: @*/
     53: PetscErrorCode  PetscObjectSetOptions(PetscObject obj,PetscOptions options)
     54: {
     57:   obj->options = options;
     58:   return(0);
     59: }

     61: /*@C
     62:    PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all
     63:    options of PetscObjectType in the database.

     65:    Collective on Object

     67:    Input Parameters:
     68: +  obj - any PETSc object, for example a Vec, Mat or KSP.
     69: -  prefix - the prefix string to prepend to option requests of the object.

     71:    Notes:
     72:    A hyphen (-) must NOT be given at the beginning of the prefix name.
     73:    The first character of all runtime options is AUTOMATICALLY the
     74:    hyphen.

     76:   Level: advanced

     78: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
     79:           PetscObjectGetOptionsPrefix(), TSSetOptionsPrefix(), SNESSetOptionsPrefix(), KSPSetOptionsPrefix()

     81: @*/
     82: PetscErrorCode  PetscObjectSetOptionsPrefix(PetscObject obj,const char prefix[])
     83: {

     88:   if (!prefix) {
     89:     PetscFree(obj->prefix);
     90:   } else {
     91:     if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");
     92:     if (prefix != obj->prefix) {
     93:       PetscFree(obj->prefix);
     94:       PetscStrallocpy(prefix,&obj->prefix);
     95:     }
     96:   }
     97:   return(0);
     98: }

    100: /*@C
    101:    PetscObjectAppendOptionsPrefix - Sets the prefix used for searching for all
    102:    options of PetscObjectType in the database.

    104:    Input Parameters:
    105: +  obj - any PETSc object, for example a Vec, Mat or KSP.
    106: -  prefix - the prefix string to prepend to option requests of the object.

    108:    Notes:
    109:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    110:    The first character of all runtime options is AUTOMATICALLY the
    111:    hyphen.

    113:   Level: advanced

    115: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
    116:           PetscObjectGetOptionsPrefix(), TSAppendOptionsPrefix(), SNESAppendOptionsPrefix(), KSPAppendOptionsPrefix()

    118: @*/
    119: PetscErrorCode  PetscObjectAppendOptionsPrefix(PetscObject obj,const char prefix[])
    120: {
    121:   char           *buf = obj->prefix;
    123:   size_t         len1,len2;

    127:   if (!prefix) return(0);
    128:   if (!buf) {
    129:     PetscObjectSetOptionsPrefix(obj,prefix);
    130:     return(0);
    131:   }
    132:   if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");

    134:   PetscStrlen(prefix,&len1);
    135:   PetscStrlen(buf,&len2);
    136:   PetscMalloc1(1+len1+len2,&obj->prefix);
    137:   PetscStrcpy(obj->prefix,buf);
    138:   PetscStrcat(obj->prefix,prefix);
    139:   PetscFree(buf);
    140:   return(0);
    141: }

    143: /*@C
    144:    PetscObjectGetOptionsPrefix - Gets the prefix of the PetscObject.

    146:    Input Parameters:
    147: .  obj - any PETSc object, for example a Vec, Mat or KSP.

    149:    Output Parameters:
    150: .  prefix - pointer to the prefix string used is returned

    152:   Level: advanced

    154: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
    155:           TSGetOptionsPrefix(), SNESGetOptionsPrefix(), KSPGetOptionsPrefix()

    157: @*/
    158: PetscErrorCode  PetscObjectGetOptionsPrefix(PetscObject obj,const char *prefix[])
    159: {
    163:   *prefix = obj->prefix;
    164:   return(0);
    165: }

    167: /*@C
    168:    PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for all
    169:    options of PetscObjectType in the database.

    171:    Input Parameters:
    172: +  obj - any PETSc object, for example a Vec, Mat or KSP.
    173: -  prefix - the prefix string to prepend to option requests of the object.

    175:    Notes:
    176:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    177:    The first character of all runtime options is AUTOMATICALLY the
    178:    hyphen.

    180:   Level: advanced

    182: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(),
    183:           PetscObjectGetOptionsPrefix(), TSPrependOptionsPrefix(), SNESPrependOptionsPrefix(), KSPPrependOptionsPrefix()

    185: @*/
    186: PetscErrorCode  PetscObjectPrependOptionsPrefix(PetscObject obj,const char prefix[])
    187: {
    188:   char           *buf;
    189:   size_t         len1,len2;

    194:   buf = obj->prefix;
    195:   if (!prefix) return(0);
    196:   if (!buf) {
    197:     PetscObjectSetOptionsPrefix(obj,prefix);
    198:     return(0);
    199:   }
    200:   if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");

    202:   PetscStrlen(prefix,&len1);
    203:   PetscStrlen(buf,&len2);
    204:   PetscMalloc1(1+len1+len2,&obj->prefix);
    205:   PetscStrcpy(obj->prefix,prefix);
    206:   PetscStrcat(obj->prefix,buf);
    207:   PetscFree(buf);
    208:   return(0);
    209: }