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