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:    Concepts: prefix^setting

 78:   Level: advanced

 80: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
 81:           PetscObjectGetOptionsPrefix(), TSSetOptionsPrefix(), SNESSetOptionsPrefix(), KSPSetOptionsPrefix()

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

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

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

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

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

115:    Concepts: prefix^setting

117:   Level: advanced

119: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
120:           PetscObjectGetOptionsPrefix(), TSAppendOptionsPrefix(), SNESAppendOptionsPrefix(), KSPAppendOptionsPrefix()

122: @*/
123: PetscErrorCode  PetscObjectAppendOptionsPrefix(PetscObject obj,const char prefix[])
124: {
125:   char           *buf = obj->prefix;
127:   size_t         len1,len2;

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

138:   PetscStrlen(prefix,&len1);
139:   PetscStrlen(buf,&len2);
140:   PetscMalloc1(1+len1+len2,&obj->prefix);
141:   PetscStrcpy(obj->prefix,buf);
142:   PetscStrcat(obj->prefix,prefix);
143:   PetscFree(buf);
144:   return(0);
145: }

147: /*@C
148:    PetscObjectGetOptionsPrefix - Gets the prefix of the PetscObject.

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

153:    Output Parameters:
154: .  prefix - pointer to the prefix string used is returned

156:    Concepts: prefix^getting

158:   Level: advanced

160: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
161:           TSGetOptionsPrefix(), SNESGetOptionsPrefix(), KSPGetOptionsPrefix()

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

173: /*@C
174:    PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for all
175:    options of PetscObjectType in the database.

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

181:    Notes:
182:    A hyphen (-) must NOT be given at the beginning of the prefix name.
183:    The first character of all runtime options is AUTOMATICALLY the
184:    hyphen.

186:    Concepts: prefix^setting

188:   Level: advanced

190: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(),
191:           PetscObjectGetOptionsPrefix(), TSPrependOptionsPrefix(), SNESPrependOptionsPrefix(), KSPPrependOptionsPrefix()

193: @*/
194: PetscErrorCode  PetscObjectPrependOptionsPrefix(PetscObject obj,const char prefix[])
195: {
196:   char           *buf;
197:   size_t         len1,len2;

202:   buf = obj->prefix;
203:   if (!prefix) return(0);
204:   if (!buf) {
205:     PetscObjectSetOptionsPrefix(obj,prefix);
206:     return(0);
207:   }
208:   if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");

210:   PetscStrlen(prefix,&len1);
211:   PetscStrlen(buf,&len2);
212:   PetscMalloc1(1+len1+len2,&obj->prefix);
213:   PetscStrcpy(obj->prefix,prefix);
214:   PetscStrcat(obj->prefix,buf);
215:   PetscFree(buf);
216:   return(0);
217: }