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:       size_t len;

 94:       PetscCall(PetscFree(obj->prefix));
 95:       PetscCall(PetscStrlen(prefix, &len));
 96:       if (len) PetscCall(PetscStrallocpy(prefix, &obj->prefix));
 97:     }
 98:   } else PetscCall(PetscFree(obj->prefix));
 99:   PetscFunctionReturn(PETSC_SUCCESS);
100: }

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

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

109:   Level: advanced

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

116: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
117:           `PetscObjectGetOptionsPrefix()`, `TSAppendOptionsPrefix()`, `SNESAppendOptionsPrefix()`, `KSPAppendOptionsPrefix()`
118: @*/
119: PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj, const char prefix[])
120: {
121:   size_t len1, len2, new_len;

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

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

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

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

146:   Output Parameter:
147: . prefix - pointer to the prefix string used is returned

149:   Level: advanced

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

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

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

170:   Level: advanced

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

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

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

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