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: {
 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:    Note:
 47:    If this is not called the object will use the default options database

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

 52:   Level: advanced

 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:    Note:
 76:    A hyphen (-) must NOT be given at the beginning of the prefix name.
 77:    The first character of all runtime options is AUTOMATICALLY the
 78:    hyphen.

 80:   Level: advanced

 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:    Note:
108:    A hyphen (-) must NOT be given at the beginning of the prefix name.
109:    The first character of all runtime options is AUTOMATICALLY the
110:    hyphen.

112:   Level: advanced

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

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

131:   PetscCall(PetscStrlen(prefix, &len1));
132:   PetscCall(PetscStrlen(buf, &len2));
133:   PetscCall(PetscMalloc1(1 + len1 + len2, &obj->prefix));
134:   PetscCall(PetscStrcpy(obj->prefix, buf));
135:   PetscCall(PetscStrcat(obj->prefix, prefix));
136:   PetscCall(PetscFree(buf));
137:   PetscFunctionReturn(PETSC_SUCCESS);
138: }

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

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

146:    Output Parameters:
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;
159:   *prefix = obj->prefix;
160:   PetscFunctionReturn(PETSC_SUCCESS);
161: }

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

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;

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

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