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: }