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()

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