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