Actual source code: prefix.c


  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 that has been set with `PetscObjectSetOptions()`

 10:    Collective

 12:    Input Parameter:
 13: .  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.

 15:    Output Parameter:
 16: .  options - the options database

 18:    Note:
 19:    If this is not called the object will use the default options database

 21:    Developer Note:
 22:    This functionality is not used in PETSc and should, perhaps, be removed

 24:   Level: advanced

 26: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
 27:           `PetscObjectGetOptionsPrefix()`, `PetscObjectSetOptions()`
 28: @*/
 29: PetscErrorCode PetscObjectGetOptions(PetscObject obj, PetscOptions *options)
 30: {
 32:   *options = obj->options;
 33:   return 0;
 34: }

 36: /*@C
 37:    PetscObjectSetOptions - Sets the options database used by the object. Call immediately after creating the object.

 39:    Collective

 41:    Input Parameters:
 42: +  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
 43: -  options - the options database, use NULL for default

 45:    Note:
 46:    If this is not called the object will use the default options database

 48:    Developer Note:
 49:    This functionality is not used in PETSc and should, perhaps, be removed

 51:   Level: advanced

 53: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
 54:           `PetscObjectGetOptionsPrefix()`, `PetscObjectGetOptions()`
 55: @*/
 56: PetscErrorCode PetscObjectSetOptions(PetscObject obj, PetscOptions options)
 57: {
 59:   obj->options = options;
 60:   return 0;
 61: }

 63: /*@C
 64:    PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all
 65:    options for the given object in the database.

 67:    Collective

 69:    Input Parameters:
 70: +  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
 71: -  prefix - the prefix string to prepend to option requests of the object.

 73:    Note:
 74:    A hyphen (-) must NOT be given at the beginning of the prefix name.
 75:    The first character of all runtime options is AUTOMATICALLY the
 76:    hyphen.

 78:   Level: advanced

 80: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
 81:           `PetscObjectGetOptionsPrefix()`, `TSSetOptionsPrefix()`, `SNESSetOptionsPrefix()`, `KSPSetOptionsPrefix()`
 82: @*/
 83: PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject obj, const char prefix[])
 84: {
 86:   if (prefix) {
 89:     if (prefix != obj->prefix) {
 90:       PetscFree(obj->prefix);
 91:       PetscStrallocpy(prefix, &obj->prefix);
 92:     }
 93:   } else PetscFree(obj->prefix);
 94:   return 0;
 95: }

 97: /*@C
 98:    PetscObjectAppendOptionsPrefix - Appends to the prefix used for searching for options for the given object in the database.

100:    Input Parameters:
101: +  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
102: -  prefix - the prefix string to prepend to option requests of the object.

104:    Note:
105:    A hyphen (-) must NOT be given at the beginning of the prefix name.
106:    The first character of all runtime options is AUTOMATICALLY the
107:    hyphen.

109:   Level: advanced

111: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
112:           `PetscObjectGetOptionsPrefix()`, `TSAppendOptionsPrefix()`, `SNESAppendOptionsPrefix()`, `KSPAppendOptionsPrefix()`
113: @*/
114: PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj, const char prefix[])
115: {
116:   char  *buf = obj->prefix;
117:   size_t len1, len2;

120:   if (!prefix) return 0;
121:   if (!buf) {
122:     PetscObjectSetOptionsPrefix(obj, prefix);
123:     return 0;
124:   }

127:   PetscStrlen(prefix, &len1);
128:   PetscStrlen(buf, &len2);
129:   PetscMalloc1(1 + len1 + len2, &obj->prefix);
130:   PetscStrcpy(obj->prefix, buf);
131:   PetscStrcat(obj->prefix, prefix);
132:   PetscFree(buf);
133:   return 0;
134: }

136: /*@C
137:    PetscObjectGetOptionsPrefix - Gets the prefix of the `PetscObject` used for searching in the options database

139:    Input Parameters:
140: .  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.

142:    Output Parameters:
143: .  prefix - pointer to the prefix string used is returned

145:   Level: advanced

147: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
148:           `TSGetOptionsPrefix()`, `SNESGetOptionsPrefix()`, `KSPGetOptionsPrefix()`
149: @*/
150: PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj, const char *prefix[])
151: {
154:   *prefix = obj->prefix;
155:   return 0;
156: }

158: /*@C
159:    PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for options of for this object in the database.

161:    Input Parameters:
162: +  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
163: -  prefix - the prefix string to prepend to option requests of the object.

165:    Note:
166:    A hyphen (-) must NOT be given at the beginning of the prefix name.
167:    The first character of all runtime options is AUTOMATICALLY the
168:    hyphen.

170:   Level: advanced

172: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`,
173:           `PetscObjectGetOptionsPrefix()`
174: @*/
175: PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject obj, const char prefix[])
176: {
177:   char  *buf;
178:   size_t len1, len2;

181:   buf = obj->prefix;
182:   if (!prefix) return 0;
183:   if (!buf) {
184:     PetscObjectSetOptionsPrefix(obj, prefix);
185:     return 0;
186:   }

189:   PetscStrlen(prefix, &len1);
190:   PetscStrlen(buf, &len2);
191:   PetscMalloc1(1 + len1 + len2, &obj->prefix);
192:   PetscStrcpy(obj->prefix, prefix);
193:   PetscStrcat(obj->prefix, buf);
194:   PetscFree(buf);
195:   return 0;
196: }