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: if this is not called the object will use the default options database

 18:   Level: advanced

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

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

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

 36:    Collective on Object

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

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

 47:    Concepts: prefix^setting

 49:   Level: advanced

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

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

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

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

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

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

 86:    Concepts: prefix^setting

 88:   Level: advanced

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

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

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

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

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

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

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

127:    Concepts: prefix^getting

129:   Level: advanced

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

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

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

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

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

157:    Concepts: prefix^setting

159:   Level: advanced

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

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

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

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