Actual source code: prefix.c
petsc-3.13.6 2020-09-29
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. Call immediately after creating the object.
10: Collective on PetscObject
12: Input Parameter:
13: . obj - any PETSc object, for example a Vec, Mat or KSP.
15: Output Parameter:
16: . options - the options database
18: Notes:
19: if this is not called the object will use the default options database
21: Level: advanced
23: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
24: PetscObjectGetOptionsPrefix(), PetscObjectSetOptions()
26: @*/
27: PetscErrorCode PetscObjectGetOptions(PetscObject obj,PetscOptions *options)
28: {
31: *options = obj->options;
32: return(0);
33: }
35: /*@C
36: PetscObjectSetOptions - Sets the options database used by the object. Call immediately after creating the object.
38: Collective on PetscObject
40: Input Parameters:
41: + obj - any PETSc object, for example a Vec, Mat or KSP.
42: - options - the options database, use NULL for default
44: Notes:
45: if this is not called the object will use the default options database
47: Level: advanced
49: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
50: PetscObjectGetOptionsPrefix(), PetscObjectGetOptions()
52: @*/
53: PetscErrorCode PetscObjectSetOptions(PetscObject obj,PetscOptions options)
54: {
57: obj->options = options;
58: return(0);
59: }
61: /*@C
62: PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all
63: options of PetscObjectType in the database.
65: Collective on Object
67: Input Parameters:
68: + obj - any PETSc object, for example a Vec, Mat or KSP.
69: - prefix - the prefix string to prepend to option requests of the object.
71: Notes:
72: A hyphen (-) must NOT be given at the beginning of the prefix name.
73: The first character of all runtime options is AUTOMATICALLY the
74: hyphen.
76: Level: advanced
78: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
79: PetscObjectGetOptionsPrefix(), TSSetOptionsPrefix(), SNESSetOptionsPrefix(), KSPSetOptionsPrefix()
81: @*/
82: PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject obj,const char prefix[])
83: {
88: if (!prefix) {
89: PetscFree(obj->prefix);
90: } else {
91: if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");
92: if (prefix != obj->prefix) {
93: PetscFree(obj->prefix);
94: PetscStrallocpy(prefix,&obj->prefix);
95: }
96: }
97: return(0);
98: }
100: /*@C
101: PetscObjectAppendOptionsPrefix - Sets the prefix used for searching for all
102: options of PetscObjectType in the database.
104: Input Parameters:
105: + obj - any PETSc object, for example a Vec, Mat or KSP.
106: - prefix - the prefix string to prepend to option requests of the object.
108: Notes:
109: A hyphen (-) must NOT be given at the beginning of the prefix name.
110: The first character of all runtime options is AUTOMATICALLY the
111: hyphen.
113: Level: advanced
115: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
116: PetscObjectGetOptionsPrefix(), TSAppendOptionsPrefix(), SNESAppendOptionsPrefix(), KSPAppendOptionsPrefix()
118: @*/
119: PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj,const char prefix[])
120: {
121: char *buf = obj->prefix;
123: size_t len1,len2;
127: if (!prefix) return(0);
128: if (!buf) {
129: PetscObjectSetOptionsPrefix(obj,prefix);
130: return(0);
131: }
132: if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");
134: PetscStrlen(prefix,&len1);
135: PetscStrlen(buf,&len2);
136: PetscMalloc1(1+len1+len2,&obj->prefix);
137: PetscStrcpy(obj->prefix,buf);
138: PetscStrcat(obj->prefix,prefix);
139: PetscFree(buf);
140: return(0);
141: }
143: /*@C
144: PetscObjectGetOptionsPrefix - Gets the prefix of the PetscObject.
146: Input Parameters:
147: . obj - any PETSc object, for example a Vec, Mat or KSP.
149: Output Parameters:
150: . prefix - pointer to the prefix string used is returned
152: Level: advanced
154: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), PetscObjectPrependOptionsPrefix(),
155: TSGetOptionsPrefix(), SNESGetOptionsPrefix(), KSPGetOptionsPrefix()
157: @*/
158: PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj,const char *prefix[])
159: {
163: *prefix = obj->prefix;
164: return(0);
165: }
167: /*@C
168: PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for all
169: options of PetscObjectType in the database.
171: Input Parameters:
172: + obj - any PETSc object, for example a Vec, Mat or KSP.
173: - prefix - the prefix string to prepend to option requests of the object.
175: Notes:
176: A hyphen (-) must NOT be given at the beginning of the prefix name.
177: The first character of all runtime options is AUTOMATICALLY the
178: hyphen.
180: Level: advanced
182: .seealso: PetscOptionsCreate(), PetscOptionsDestroy(), PetscObjectSetOptionsPrefix(), PetscObjectAppendOptionsPrefix(),
183: PetscObjectGetOptionsPrefix(), TSPrependOptionsPrefix(), SNESPrependOptionsPrefix(), KSPPrependOptionsPrefix()
185: @*/
186: PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject obj,const char prefix[])
187: {
188: char *buf;
189: size_t len1,len2;
194: buf = obj->prefix;
195: if (!prefix) return(0);
196: if (!buf) {
197: PetscObjectSetOptionsPrefix(obj,prefix);
198: return(0);
199: }
200: if (prefix[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hypen");
202: PetscStrlen(prefix,&len1);
203: PetscStrlen(buf,&len2);
204: PetscMalloc1(1+len1+len2,&obj->prefix);
205: PetscStrcpy(obj->prefix,prefix);
206: PetscStrcat(obj->prefix,buf);
207: PetscFree(buf);
208: return(0);
209: }