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:   Level: advanced

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

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

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

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

 40:    Collective

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

 46:   Level: advanced

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

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

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

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

 69:    Collective

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

 75:   Level: advanced

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

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

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

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

107:   Level: advanced

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

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

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

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

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

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

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

147:   Level: advanced

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

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

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

168:   Level: advanced

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

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

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

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