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: }