Actual source code: prefix.c
petsc-3.10.5 2019-03-28
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:    PetscObjectSetOptions - Sets the options database used by the object

     10:    Collective on PetscObject

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

     16:    Notes:
     17:     if this is not called the object will use the default options database

     19:   Level: advanced

     21: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
     22:           PetscObjectGetOptionsPrefix()

     24: @*/
     25: PetscErrorCode  PetscObjectSetOptions(PetscObject obj,PetscOptions options)
     26: {
     29:   obj->options = options;
     30:   return(0);
     31: }

     33: /*@C
     34:    PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all
     35:    options of PetscObjectType in the database.

     37:    Collective on Object

     39:    Input Parameters:
     40: .  obj - any PETSc object, for example a Vec, Mat or KSP.
     41: .  prefix - the prefix string to prepend to option requests of the object.

     43:    Notes:
     44:    A hyphen (-) must NOT be given at the beginning of the prefix name.
     45:    The first character of all runtime options is AUTOMATICALLY the
     46:    hyphen.

     48:    Concepts: prefix^setting

     50:   Level: advanced

     52: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
     53:           PetscObjectGetOptionsPrefix(), TSSetOptionsPrefix(), SNESSetOptionsPrefix(), KSPSetOptionsPrefix()

     55: @*/
     56: PetscErrorCode  PetscObjectSetOptionsPrefix(PetscObject obj,const char prefix[])
     57: {

     62:   if (!prefix) {
     63:     PetscFree(obj->prefix);
     64:   } else {
     65:     if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");
     66:     if (prefix != obj->prefix) {
     67:       PetscFree(obj->prefix);
     68:       PetscStrallocpy(prefix,&obj->prefix);
     69:     }
     70:   }
     71:   return(0);
     72: }

     74: /*@C
     75:    PetscObjectAppendOptionsPrefix - Sets the prefix used for searching for all
     76:    options of PetscObjectType in the database.

     78:    Input Parameters:
     79: .  obj - any PETSc object, for example a Vec, Mat or KSP.
     80: .  prefix - the prefix string to prepend to option requests of the object.

     82:    Notes:
     83:    A hyphen (-) must NOT be given at the beginning of the prefix name.
     84:    The first character of all runtime options is AUTOMATICALLY the
     85:    hyphen.

     87:    Concepts: prefix^setting

     89:   Level: advanced

     91: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
     92:           PetscObjectGetOptionsPrefix(), TSAppendOptionsPrefix(), SNESAppendOptionsPrefix(), KSPAppendOptionsPrefix()

     94: @*/
     95: PetscErrorCode  PetscObjectAppendOptionsPrefix(PetscObject obj,const char prefix[])
     96: {
     97:   char           *buf = obj->prefix;
     99:   size_t         len1,len2;

    103:   if (!prefix) return(0);
    104:   if (!buf) {
    105:     PetscObjectSetOptionsPrefix(obj,prefix);
    106:     return(0);
    107:   }
    108:   if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");

    110:   PetscStrlen(prefix,&len1);
    111:   PetscStrlen(buf,&len2);
    112:   PetscMalloc1(1+len1+len2,&obj->prefix);
    113:   PetscStrcpy(obj->prefix,buf);
    114:   PetscStrcat(obj->prefix,prefix);
    115:   PetscFree(buf);
    116:   return(0);
    117: }

    119: /*@C
    120:    PetscObjectGetOptionsPrefix - Gets the prefix of the PetscObject.

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

    125:    Output Parameters:
    126: .  prefix - pointer to the prefix string used is returned

    128:    Concepts: prefix^getting

    130:   Level: advanced

    132: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
    133:           TSGetOptionsPrefix(), SNESGetOptionsPrefix(), KSPGetOptionsPrefix()

    135: @*/
    136: PetscErrorCode  PetscObjectGetOptionsPrefix(PetscObject obj,const char *prefix[])
    137: {
    141:   *prefix = obj->prefix;
    142:   return(0);
    143: }

    145: /*@C
    146:    PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for all
    147:    options of PetscObjectType in the database.

    149:    Input Parameters:
    150: .  obj - any PETSc object, for example a Vec, Mat or KSP.
    151: .  prefix - the prefix string to prepend to option requests of the object.

    153:    Notes:
    154:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    155:    The first character of all runtime options is AUTOMATICALLY the
    156:    hyphen.

    158:    Concepts: prefix^setting

    160:   Level: advanced

    162: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(),
    163:           PetscObjectGetOptionsPrefix(), TSPrependOptionsPrefix(), SNESPrependOptionsPrefix(), KSPPrependOptionsPrefix()

    165: @*/
    166: PetscErrorCode  PetscObjectPrependOptionsPrefix(PetscObject obj,const char prefix[])
    167: {
    168:   char           *buf;
    169:   size_t         len1,len2;

    174:   buf = obj->prefix;
    175:   if (!prefix) return(0);
    176:   if (!buf) {
    177:     PetscObjectSetOptionsPrefix(obj,prefix);
    178:     return(0);
    179:   }
    180:   if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");

    182:   PetscStrlen(prefix,&len1);
    183:   PetscStrlen(buf,&len2);
    184:   PetscMalloc1(1+len1+len2,&obj->prefix);
    185:   PetscStrcpy(obj->prefix,prefix);
    186:   PetscStrcat(obj->prefix,buf);
    187:   PetscFree(buf);
    188:   return(0);
    189: }