1: /*
  2:      Provides utility routines for manulating any type of PETSc object.
  3: */
  4: #include <petsc/private/petscimpl.h>

  6: /*@
  7:   PetscObjectGetOptions - Gets the options database used by the object that has been set with `PetscObjectSetOptions()`

  9:   Collective

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

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

 17:   Level: advanced

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

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

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

 36: /*@
 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:   Level: advanced

 47:   Note:
 48:   If this is not called the object will use the default options database

 50:   Developer Notes:
 51:   This functionality is not used in PETSc and should, perhaps, be removed

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

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

 68:   Collective

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

 74:   Level: advanced

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

 81: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
 82:           `PetscObjectGetOptionsPrefix()`, `TSSetOptionsPrefix()`, `SNESSetOptionsPrefix()`, `KSPSetOptionsPrefix()`
 83: @*/
 84: PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject obj, const char prefix[])
 85: {
 86:   PetscFunctionBegin;
 88:   if (prefix) {
 89:     PetscAssertPointer(prefix, 2);
 90:     PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen");
 91:     if (prefix != obj->prefix) {
 92:       PetscCall(PetscFree(obj->prefix));
 93:       PetscCall(PetscStrallocpy(prefix, &obj->prefix));
 94:     }
 95:   } else PetscCall(PetscFree(obj->prefix));
 96:   PetscFunctionReturn(PETSC_SUCCESS);
 97: }

 99: /*@
100:   PetscObjectAppendOptionsPrefix - Appends to the prefix used for searching for options for the given object in the database.

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

106:   Level: advanced

108:   Note:
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: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
114:           `PetscObjectGetOptionsPrefix()`, `TSAppendOptionsPrefix()`, `SNESAppendOptionsPrefix()`, `KSPAppendOptionsPrefix()`
115: @*/
116: PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj, const char prefix[])
117: {
118:   size_t len1, len2, new_len;

120:   PetscFunctionBegin;
122:   if (!prefix) PetscFunctionReturn(PETSC_SUCCESS);
123:   if (!obj->prefix) {
124:     PetscCall(PetscObjectSetOptionsPrefix(obj, prefix));
125:     PetscFunctionReturn(PETSC_SUCCESS);
126:   }
127:   PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen");

129:   PetscCall(PetscStrlen(obj->prefix, &len1));
130:   PetscCall(PetscStrlen(prefix, &len2));
131:   new_len = len1 + len2 + 1;
132:   PetscCall(PetscRealloc(new_len * sizeof(*obj->prefix), &obj->prefix));
133:   PetscCall(PetscStrncpy(obj->prefix + len1, prefix, len2 + 1));
134:   PetscFunctionReturn(PETSC_SUCCESS);
135: }

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

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

143:   Output Parameter:
144: . prefix - pointer to the prefix string used is returned

146:   Level: advanced

148: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
149:           `TSGetOptionsPrefix()`, `SNESGetOptionsPrefix()`, `KSPGetOptionsPrefix()`
150: @*/
151: PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj, const char *prefix[])
152: {
153:   PetscFunctionBegin;
155:   PetscAssertPointer(prefix, 2);
156:   *prefix = obj->prefix;
157:   PetscFunctionReturn(PETSC_SUCCESS);
158: }

160: /*@
161:   PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for options of for this object in the database.

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

167:   Level: advanced

169:   Note:
170:   A hyphen (-) must NOT be given at the beginning of the prefix name.
171:   The first character of all runtime options is AUTOMATICALLY the
172:   hyphen.

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

182:   PetscFunctionBegin;
184:   if (!prefix) PetscFunctionReturn(PETSC_SUCCESS);
185:   if (!obj->prefix) {
186:     PetscCall(PetscObjectSetOptionsPrefix(obj, prefix));
187:     PetscFunctionReturn(PETSC_SUCCESS);
188:   }
189:   PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen");

191:   PetscCall(PetscStrlen(prefix, &len1));
192:   PetscCall(PetscStrlen(obj->prefix, &len2));
193:   buf     = obj->prefix;
194:   new_len = len1 + len2 + 1;
195:   PetscCall(PetscMalloc1(new_len, &obj->prefix));
196:   PetscCall(PetscStrncpy(obj->prefix, prefix, len1 + 1));
197:   PetscCall(PetscStrncpy(obj->prefix + len1, buf, len2 + 1));
198:   PetscCall(PetscFree(buf));
199:   PetscFunctionReturn(PETSC_SUCCESS);
200: }