GCC Code Coverage Report


Directory: ./
Coverage: low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%
Coverage Exec / Excl / Total
Lines: 60.5% 26 / 1 / 44
Functions: 66.7% 6 / 1 / 10
Branches: 41.2% 7 / 1 / 18

src/utilities/idf/Workspace.hpp
Line Branch Exec Source
1 /***********************************************************************************************************************
2 * OpenStudio(R), Copyright (c) Alliance for Energy Innovation, LLC.
3 * See also https://openstudio.net/license
4 ***********************************************************************************************************************/
5
6 #ifndef UTILITIES_IDF_WORKSPACE_HPP
7 #define UTILITIES_IDF_WORKSPACE_HPP
8
9 #include "../UtilitiesAPI.hpp"
10 #include "ValidityEnums.hpp"
11 #include "Handle.hpp"
12
13 #include "../core/Logger.hpp"
14 #include "../core/Path.hpp"
15
16 #include <string>
17 #include <ostream>
18 #include <vector>
19 #include <set>
20
21 namespace openstudio {
22
23 // forward declarations
24 class IddFile;
25 struct IddFileType;
26 class IddObject;
27 struct IddObjectType;
28 class IdfFile;
29 class IdfObject;
30 class WorkspaceObject;
31 class WorkspaceObjectOrder;
32 class ValidityReport;
33 class VersionString;
34
35 class Quantity;
36
37 class ProgressBar;
38
39 namespace detail {
40 class Workspace_Impl;
41 class WorkspaceObject_Impl;
42 } // namespace detail
43
44 /** Workspace holds a collection of interconnected \link WorkspaceObject WorkspaceObjects\endlink.
45 * Similar to IdfFile, Workspace represents data (typically a whole or partial building energy
46 * model) in EnergyPlus Input Data File (IDF) format, and each instance of Workspace is
47 * constructed from a specific IddFile (either explicitly or using the IddFactory plus an
48 * IddFileType.) Workspace is shared so that changes to a copy of a Workspace changes the
49 * original as well.
50 *
51 * Workspace contains the following types of \link WorkspaceObject WorkspaceObjects\endlink:
52 * - unique objects, indexed by type, should be present 0-1 times
53 * - objects with no associated reference lists, indexed by type and first field value, present
54 * 0-inf times
55 * - objects with one or more associated reference lists, indexed by type, name, and
56 * reference list name, present 0-inf times
57 * Workspaces based on EnergyPlus IDDs are stuck with the above ways of identifying referenced
58 * objects in serialized form. As of Version 0.7.4, OpenStudio IDD serializes a Universal Unique
59 * Identifier (UUID) for each object, and uses this identifier to make inter-object connections.
60 * With this change, it is possible for an IdfObject field to use the OpenStudio-specific
61 * \\object-list AllObjects (see OS:ComponentData for an example).
62 *
63 * Although Workspace and IdfFile share many important characteristics, there is no direct
64 * inheritance relationship between the two since their implementations are fundamentally
65 * different. */
66 class UTILITIES_API Workspace
67 {
68 public:
69 /** @name Constructors and Destructors */
70 //@{
71
72 /** Default constructor assumes StrictnessLevel::Draft and IddFileType::EnergyPlus. Adds a
73 * versionObject with the version identifier set according to the version registered for
74 * iddFileType in the IddFactory. */
75 Workspace();
76
77 /** Construct IddFileType::EnergyPlus Workspace at StrictnessLevel level. Adds a versionObject
78 * with the version identifier set according to the version registered for iddFileType in the
79 * IddFactory. If level == StrictnessLevel::Final, Workspace can be invalid
80 * post-construction. */
81 Workspace(StrictnessLevel level);
82
83 /** Default constructor. User can specify IddFileType (IddFileType::EnergyPlus or IddFileType::OpenStudio)
84 * and StrictnessLevel. Adds a versionObject with the version identifier set according to the version
85 * registered for iddFileType in the IddFactory.
86 * If level == StrictnessLevel::Final, Workspace can be invalid post-construction. */
87 Workspace(StrictnessLevel level, IddFileType iddFileType);
88
89 /** Construct from idfFile. The new Workspace inherits idfFile's IddFile. Each IdfObject in
90 * idfFile is used to construct a WorkspaceObject that is held by the new Workspace, and is
91 * equivalent to, but completely separate from, the IdfObject. (All object data is cloned.)
92 *
93 * If the Workspace so constructed is not valid at the specified StrictnessLevel, all of the
94 * newly created objects are removed, and the constructor returns an empty Workspace with
95 * StrictnessLevel None. Problems may be diagnosed by calling idfFile.validityReport(level). */
96 Workspace(const IdfFile& idfFile, StrictnessLevel level = openstudio::StrictnessLevel::Minimal);
97
98 /** Copy constructor, shares data with other Workspace. */
99 Workspace(const Workspace& other);
100
101 /** Create a deep copy (clone) of all data in this Workspace and return the result in a new
102 * Workspace object. Virtual implementation preserves original Workspace type. Example usage
103 * for derived class:
104 *
105 * \code
106 * model::Model model;
107 * Workspace clonedModelAsWorkspace = model.clone();
108 * model::Model clonedModel = clonedModelAsWorkspace.cast<model::Model>();
109 * \endcode
110 *
111 * If keepHandles, then new handles will not be assigned to the cloned objects. This feature
112 * should be used with care, as reuse of unique object identifiers could lead to changing data
113 * in the wrong Workspace. */
114 Workspace clone(bool keepHandles = false) const;
115
116 /** Clone just the objects referenced by handles into a new Workspace. All non-object data is
117 * also cloned. If keepHandles, then new handles will not be assigned to the cloned objects.
118 * Virtual implementation, and similar usage to clone. */
119 Workspace cloneSubset(const std::vector<Handle>& handles, bool keepHandles = false,
120 StrictnessLevel level = openstudio::StrictnessLevel::Draft) const;
121
122 /** Swaps underlying data between this workspace and other. Throws if other and this
123 * are not of the same type (must both be plain Workspaces, model::Models, or
124 * model::Components). */
125 void swap(Workspace& other);
126
127 9211481 virtual ~Workspace() = default;
128
129 //@}
130 /** @name Getters */
131 //@{
132
133 /// Returns the strictness level under which this Workspace is currently operating.
134 StrictnessLevel strictnessLevel() const;
135
136 /** Returns the version of this model, as determined by the IddFile header. */
137 VersionString version() const;
138
139 /** Returns the underlying IddFile (the schema for this Workspace). */
140 IddFile iddFile() const;
141
142 /** Returns the underlying IddFile's IddFileType. */
143 IddFileType iddFileType() const;
144
145 /** Returns the IddObject corresponding to type if it is available from the underlying IddFile.
146 * Otherwise the return value evaluates to false. */
147 boost::optional<IddObject> getIddObject(const IddObjectType& type) const;
148
149 /** Returns the object name associated with handle. */
150 boost::optional<std::string> name(const Handle& handle) const;
151
152 /** Get an object from its handle. */
153 boost::optional<WorkspaceObject> getObject(Handle handle) const;
154
155 /** Returns all the objects in this Workspace, excluding any version objects. If sorted, the
156 * objects are returned in the preferred order. */
157 std::vector<WorkspaceObject> objects(bool sorted = false) const;
158
159 /** Returns the handles of all the objects in this Workspace, excluding those of any version
160 * objects. If sorted, the handles are returned in the preferred order. */
161 std::vector<Handle> handles(bool sorted = false) const;
162
163 /** Get all the objects in the current workspace that can have a URL entry, that is, they have a
164 * URL IddField in their iddObject(). */
165 std::vector<WorkspaceObject> objectsWithURLFields() const;
166
167 /** Return the version object in this Workspace, if it exists and is unique. */
168 boost::optional<WorkspaceObject> versionObject() const;
169
170 /** Get objects from their handles. */
171 std::vector<WorkspaceObject> getObjects(const std::vector<Handle>& handles) const;
172
173 /** Returns all objects named name (case insensitive). If exactMatch == false, will return
174 * all objects with name or name plus an integer suffix. */
175 std::vector<WorkspaceObject> getObjectsByName(const std::string& name, bool exactMatch = true) const;
176
177 /** Returns all objects of type objectType (e.g. IddObjectType::Zone,
178 * IddObjectType("OS:Construction")). */
179 std::vector<WorkspaceObject> getObjectsByType(IddObjectType objectType) const;
180
181 /** Returns all objects with .iddObject() == objectType. */
182 std::vector<WorkspaceObject> getObjectsByType(const IddObject& objectType) const;
183
184 /** Returns the first object found of type objectType and named name (case insensitive,
185 * exact match). */
186 boost::optional<WorkspaceObject> getObjectByTypeAndName(IddObjectType objectType, const std::string& name) const;
187
188 /** Returns all objects named name or name plus an integer suffix (case insensitive). */
189 std::vector<WorkspaceObject> getObjectsByTypeAndName(IddObjectType objectType, const std::string& name) const;
190
191 /** Returns all objects in the reference list referenceName */
192 std::vector<WorkspaceObject> getObjectsByReference(const std::string& referenceName) const;
193
194 /** Returns all objects in at least one of the reference lists in referenceNames. */
195 std::vector<WorkspaceObject> getObjectsByReference(const std::vector<std::string>& referenceNames) const;
196
197 /** Returns the first object found that is in at least one of the reference lists in
198 * referenceNames and named name (case insensitive, but exact match). Does not look for
199 * conflicts. */
200 boost::optional<WorkspaceObject> getObjectByNameAndReference(const std::string& name, const std::vector<std::string>& referenceNames) const;
201
202 /** Overloaded functions that take in a std::string instead of an IddObjectType.
203 * They will internally create an IddObjectType (which may throw!) then forward to the overload method that takes IddObjectType
204 * eg: `getObjectsByType(IddObjectType objectType)` */
205 std::vector<WorkspaceObject> getObjectsByType(const std::string& objectTypeName) const;
206 boost::optional<WorkspaceObject> getObjectByTypeAndName(const std::string& objectTypeName, const std::string& name) const;
207 std::vector<WorkspaceObject> getObjectsByTypeAndName(const std::string& objectTypeName, const std::string& name) const;
208
209 /** Returns true if fast naming is enabled. Fast naming creates UUID-based names for new
210 * objects and does not do any name conflict checking. */
211 bool fastNaming() const;
212
213 //@}
214 /** @name Setters */
215 //@{
216
217 /** Set the StrictnessLevel to level. If level > strictnessLevel(), this method may
218 * leave the strictness unchanged and return false to indicate that the collection does not
219 * satisfy those requirements. To diagnose any issues, print the validityReport(level). */
220 bool setStrictnessLevel(StrictnessLevel level);
221
222 /** Add a clone of idfObject to Workspace. May rename the new object to avoid name
223 * conflicts with exiting objects. If IdfObject has handle it will be preserved.*/
224 boost::optional<WorkspaceObject> addObject(const IdfObject& idfObject);
225
226 /** Insert idfObject into this Workspace. Looks for an equivalent object first, only adding a
227 * clone if necessary. Implementation is equivalent to inserting a Workspace with only
228 * idfObject added to it. If successful (equivalent object found, or object successfully
229 * added), the new object is returned. Otherwise, the return value evaluates to false.
230 * If IdfObjects has handle it will be preserved.*/
231 boost::optional<WorkspaceObject> insertObject(const IdfObject& idfObject);
232
233 /** Add clones of idfObjects to Workspace, if possible. Use this function to add multiple
234 * objects at once to avoid losing pointer (name/UUID reference) information. If successful,
235 * returned vector is of the same size, and is in the same order, as idfObjects. Otherwise,
236 * return value will be .empty(). If IdfObjects have handles they will be preserved.*/
237 std::vector<WorkspaceObject> addObjects(const std::vector<IdfObject>& idfObjects, bool checkNames = true);
238
239 /** Insert idfObjects into Workspace, if possible. Looks for equivalent objects first, then
240 * adds if necessary. If successful, new and equivalent objects will be returned in same order
241 * as idfObjects. Otherwise, return value will be .empty(). Equivalence is determined by
242 * creating a working Workspace with idfObjects as its contents, then looking for equivalence
243 * between the resulting WorkspaceObjects and this Workspace's objects.
244 * If IdfObjects have handles they will be preserved.*/
245 std::vector<WorkspaceObject> insertObjects(const std::vector<IdfObject>& idfObjects);
246
247 /** Adds objectToAdd and inserts objectsToInsert into Workspace, if possible. If successful,
248 * returned vector is of the same size, and is in the same order, as the concatenation of
249 * objectsToAdd and objectsToInsert. Otherwise, return value will be .empty().
250 * If IdfObjects have handles they will be preserved.*/
251 std::vector<WorkspaceObject> addAndInsertObjects(const std::vector<IdfObject>& objectsToAdd, const std::vector<IdfObject>& objectsToInsert);
252
253 /** Add objects to this Workspace, if possible. All objects are assumed to be from the same
254 * workspace, possibly this one. All data is cloned. Upon successful completion, the returned
255 * vector is of the same size, and is in the same order, as objects. Pointers are handled as
256 * follows:
257 *
258 * \li objects[i] -> objects[j] becomes result[i] -> result[j]
259 * \li objects[i] -> external object becomes NULL or result[i] -> external object depending on
260 * whether objects[0].workspace() == *this.
261 * \li external object -> objects[i] is not in any way duplicated in result */
262 std::vector<WorkspaceObject> addObjects(const std::vector<WorkspaceObject>& objects, bool checkNames = true);
263
264 /** Insert objects into this Workspace, if possible. All objects are assumed to be from the same
265 * workspace, possibly this one. Data is only cloned if no equivalent object is located in this
266 * Workspace. Equivalence is defined as dataFieldsEqual and managedObjectListsNonConflicting.
267 * (If objects[0].workspace() == *this, this method call is trivial and objects is returned
268 * directly.) Upon successful completion, the returned vector is of the same size, and is in the
269 * same order, as objects. Pointers are handled as follows:
270 *
271 * \li objects[i] -> objects[j] becomes result[i] -> result[j]
272 * \li objects[i] -> external object becomes NULL or result[i] -> external object depending on
273 * whether objects[0].workspace() == *this.
274 * \li external object -> objects[i] only becomes external object -> result[i] if
275 * objects[0].workspace() == *this */
276 std::vector<WorkspaceObject> insertObjects(const std::vector<WorkspaceObject>& objects);
277
278 /** Add objectsToAdd and insert objectToInsert into this Workspace. All objects from both vectors
279 * are assumed to be from the same workspace, possibly this one. All relationships between the
280 * objects in both vectors (within and between vectors) are retained. Returns the resulting
281 * objects in the order implied by concatenating objectsToAdd and objectsToInsert. A new object
282 * is always created for each object in objectsToAdd; equivalent objects (dataFieldsEqual and
283 * managedObjectListsNonConflicting) may be returned for objectsToInsert. */
284 std::vector<WorkspaceObject> addAndInsertObjects(const std::vector<WorkspaceObject>& objectsToAdd,
285 const std::vector<WorkspaceObject>& objectsToInsert);
286
287 /** Add objectsToAdd and insert objectsToInsert into this Workspace. This method differs from the
288 * basic addAndInsertObjects for WorkspaceObjects in that the objectsToInsert are grouped.
289 * Equivalent objects are evaluated as a whole for each group (sub-vector) of objectsToInsert.
290 * That is, if no equivalent is found for any one object in a given group, the whole group is
291 * added to the workspace. */
292 std::vector<WorkspaceObject> addAndInsertObjects(const std::vector<WorkspaceObject>& objectsToAdd,
293 const std::vector<std::vector<WorkspaceObject>>& objectsToInsert);
294
295 /** Swap currentObject and newObject. To proceed, the objects must be compatible, that is,
296 * all source fields pointing to currentObject must be reset-able to newObject, and
297 * (if keepTargets), newObject must be able to point to the same target objects as
298 * currentObject. If successful, the return value is true, and the data in currentObject and
299 * newObject will have been swapped. Otherwise, the return value evaluates to false. */
300 bool swap(WorkspaceObject& currentObject, IdfObject& newObject, bool keepTargets = false);
301
302 /** Remove object from Workspace with the expectation that it will be destructed.
303 * This function removes only the object specified by handle it is not overridden
304 * to "do the right thing" for ModelObject.
305 */
306 bool removeObject(const Handle& handle);
307
308 /** Remove objects from Workspace with the expectation that they will be destructed.
309 * This function removes only the objects specified by handles it is not overridden
310 * to "do the right thing" for ModelObjects.
311 */
312 bool removeObjects(const std::vector<Handle>& handles);
313
314 /** Setting fast naming to true reduces the time taken to create and verify the uniqueness
315 * of names by using a UUID as the name. The name UUID is not the same as the object's
316 * handle. */
317 void setFastNaming(bool fastNaming);
318
319 //@}
320 /** @name Object Order */
321 //@{
322
323 /** Access the WorkspaceOrderObject used by the workspace to provide user-specified
324 * ordering of objects. */
325 WorkspaceObjectOrder order();
326
327 /** Access the WorkspaceOrderObject used by the workspace to provide user-specified
328 * ordering of objects. */
329 const WorkspaceObjectOrder order() const;
330
331 /** Sort objects using order(). */
332 std::vector<WorkspaceObject> sort(const std::vector<WorkspaceObject>& objects) const;
333
334 /** Sort handles using order(). */
335 std::vector<Handle> sort(const std::vector<Handle>& handles) const;
336
337 //@}
338 /** @name Queries */
339 //@{
340
341 /** Return the total number of objects in the workspace, ignoring version objects. */
342 unsigned numObjects() const;
343
344 /** Return the number of objects of IddObjectType type in the workspace. */
345 unsigned numObjectsOfType(IddObjectType type) const;
346
347 /** Return the number of objects by full IddObject type. */
348 unsigned numObjectsOfType(const IddObject& objectType) const;
349
350 /** True if handle corresponds to an object in this workspace. */
351 bool isMember(const Handle& handle) const;
352
353 /** True if an \\object-list field referencing the given names can point to this object. */
354 bool canBeTarget(const Handle& handle, const std::set<std::string>& referenceListNames) const;
355
356 /** True if the IddObject of type is in iddFile(). */
357 bool isInIddFile(IddObjectType type) const;
358
359 /** Returns the next name in the pattern 'name << " " << int'. If fillIn, will use unused integer
360 * values smaller than the largest one. */
361 std::string nextName(const std::string& name, bool fillIn) const;
362
363 /** Returns the next name in the pattern 'iddObject().name() << " " << int' for iddObjectType.
364 * If fillIn, will use unused integer values smaller than the largest one. */
365 std::string nextName(const IddObjectType& iddObjectType, bool fillIn) const;
366
367 /** Returns true if this Workspace is valid at strictnessLevel(). */
368 bool isValid() const;
369
370 /** Returns true if this Workspace is valid, that is, has no errors at or below level. */
371 bool isValid(StrictnessLevel level) const;
372
373 /** Returns a ValidityReport for this IdfFile containing all errors at or below
374 * strictnessLevel(). */
375 ValidityReport validityReport() const;
376
377 /** Returns a ValidityReport for this Workspace containing all errors at or below level. */
378 ValidityReport validityReport(StrictnessLevel level) const;
379
380 bool operator==(const Workspace& other) const;
381
382 bool operator!=(const Workspace& other) const;
383
384 //@}
385 /** @name Serialization and File Management */
386 //@{
387
388 /** Save this Workspace to path p. Will construct the parent folder if necessary and if its
389 * parent folder already exists. Will only overwrite an existing file if overwrite==true. If no
390 * extension is provided will use modelFileExtension() for files using IddFileType::OpenStudio,
391 * and 'idf' otherwise. Returns true if the save operation is successful; false otherwise. */
392 bool save(const openstudio::path& p, bool overwrite = false);
393
394 /** Load a Workspace from path using the IddFactory, and choosing iddFileType based on file
395 * extension, if possible. (IddFileType::OpenStudio if extension is modelFileExtension() or
396 * componentFileExtension(), IddFileType::EnergyPlus otherwise.) */
397 static boost::optional<Workspace> load(const openstudio::path& p);
398
399 /** Load a Workspace from path using the IddFactory and iddFileType. */
400 static boost::optional<Workspace> load(const openstudio::path& p, const IddFileType& iddFileType);
401
402 /** Load a Workspace from path using iddFile. */
403 static boost::optional<Workspace> load(const openstudio::path& p, const IddFile& iddFile);
404
405 /** Returns an IdfFile equivalent to this Workspace. If the objects have handle fields (as in the
406 * OpenStudio IDD), pointers between objects are serialized as handles, otherwise they are
407 * serialized as names. */
408 IdfFile toIdfFile() const;
409
410 //@}
411 /** @name GUI Helpers */
412 //@{
413
414 // connect a progress bar
415 bool connectProgressBar(openstudio::ProgressBar& progressBar);
416
417 // disconnect a progress bar
418 bool disconnectProgressBar(openstudio::ProgressBar& progressBar);
419
420 //@}
421 /** @name Type Casing */
422 //@{
423
424 /** Cast to type T. Throws std::bad_cast() if this is not a T. */
425 template <typename T>
426 379555 T cast() const {
427 379555 std::shared_ptr<typename T::ImplType> impl = this->getImpl<typename T::ImplType>();
428
2/6
openstudio::Workspace openstudio::Workspace::cast<openstudio::Workspace>() const:
✗ Branch 1 not taken.
✓ Branch 2 taken 958 times.
openstudio::model::Component openstudio::Workspace::cast<openstudio::model::Component>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
openstudio::model::Model openstudio::Workspace::cast<openstudio::model::Model>() const:
✗ Branch 1 not taken.
✓ Branch 2 taken 378597 times.
379555 if (!impl) {
429 ✗ throw(std::bad_cast());
430 }
431
2/3
openstudio::Workspace openstudio::Workspace::cast<openstudio::Workspace>() const:
✓ Branch 3 taken 958 times.
openstudio::model::Component openstudio::Workspace::cast<openstudio::model::Component>() const:
✗ Branch 3 not taken.
openstudio::model::Model openstudio::Workspace::cast<openstudio::model::Model>() const:
✓ Branch 3 taken 378597 times.
759110 return T(std::move(impl));
432 379555 }
433
434 /** Cast to boost::optional<T>. Returns boost::none on failure of cast. */
435 template <typename T>
436 4 boost::optional<T> optionalCast() const {
437 4 boost::optional<T> result;
438 4 std::shared_ptr<typename T::ImplType> impl = this->getImpl<typename T::ImplType>();
439
1/4
boost::optional<openstudio::model::Component> openstudio::Workspace::optionalCast<openstudio::model::Component>() const:
✓ Branch 1 taken 4 times.
✗ Branch 2 not taken.
boost::optional<openstudio::model::Model> openstudio::Workspace::optionalCast<openstudio::model::Model>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
4 if (impl) {
440
2/4
boost::optional<openstudio::model::Component> openstudio::Workspace::optionalCast<openstudio::model::Component>() const:
✓ Branch 3 taken 4 times.
✓ Branch 6 taken 4 times.
boost::optional<openstudio::model::Model> openstudio::Workspace::optionalCast<openstudio::model::Model>() const:
✗ Branch 3 not taken.
✗ Branch 6 not taken.
4 result = T(std::move(impl));
441 }
442 8 return result;
443 4 }
444
445 // get the impl
446 template <typename T>
447 1129660 std::shared_ptr<T> getImpl() const {
448 1129660 return std::dynamic_pointer_cast<T>(m_impl);
449 }
450
451 //@}
452 protected:
453 using ImplType = detail::Workspace_Impl;
454
455 friend class WorkspaceObject;
456 friend class detail::WorkspaceObject_Impl;
457 friend class detail::Workspace_Impl;
458
459 /** Protected constructor from impl. */
460 Workspace(std::shared_ptr<detail::Workspace_Impl> impl);
461
462 /** Returns all objects, including the versionObject. Protected in public class. */
463 std::vector<WorkspaceObject> allObjects() const;
464
465 virtual void addVersionObject();
466
467 private:
468 // configure logging
469 − REGISTER_LOGGER("utilities.idf.Workspace");
470
471 // pointer to implementation
472 std::shared_ptr<detail::Workspace_Impl> m_impl;
473 };
474
475 /** \relates Workspace */
476 using OptionalWorkspace = boost::optional<Workspace>;
477
478 /** \relates Workspace */
479 using WorkspaceVector = std::vector<Workspace>;
480
481 /** \relates Workspace */
482 UTILITIES_API std::ostream& operator<<(std::ostream& os, const Workspace& workspace);
483
484 } // namespace openstudio
485
486 #endif //UTILITIES_IDF_WORKSPACE_HPP
487