GCC Code Coverage Report


Directory: ./
Coverage: low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%
Coverage Exec / Excl / Total
Lines: 90.0% 9 / 1 / 11
Functions: 88.9% 8 / 1 / 10
Branches: 63.6% 14 / 1 / 23

src/utilities/data/Attribute.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_DATA_ATTRIBUTE_HPP
7 #define UTILITIES_DATA_ATTRIBUTE_HPP
8
9 #include "../UtilitiesAPI.hpp"
10
11 #include "../core/Enum.hpp"
12 #include "../core/Logger.hpp"
13 #include "../core/Path.hpp"
14 #include "../core/UUID.hpp"
15 #include "../core/Optional.hpp"
16
17 #include <boost/optional.hpp>
18
19 #include <variant>
20
21 namespace pugi {
22 class xml_document;
23 class xml_node;
24 } // namespace pugi
25
26 namespace Json {
27 class Value;
28 }
29
30 namespace openstudio {
31
32 class Attribute;
33
34 namespace detail {
35 class Attribute_Impl;
36 class EndUsesAttribute_Impl;
37 } // namespace detail
38 // TODO: do I really need to add 'unsigned int' as a type, or can I store as int instead (we store AttributeValueType too...)
39 // Note JM 2018-11-28:
40 // we add std::monostate to allow the variant to be empty basically
41 using OSAttributeVariant = std::variant<std::monostate, bool, double, int, unsigned int, std::string, std::vector<Attribute>>;
42
43 UTILITIES_API std::ostream& operator<<(std::ostream& os, const OSAttributeVariant& attributeVariant);
44
45 // clang-format off
46
47 /** \class AttributeValueType
48 * \brief A listing of data types that can be held in an Attribute.
49 * \details See the OPENSTUDIO_ENUM documentation in utilities/core/Enum.hpp. The actual macro call is:
50 * \code
51 OPENSTUDIO_ENUM(AttributeValueType,
52 ((Boolean)(Boolean)(0))
53 ((Double)(Double)(1))
54 // ((Quantity)(Quantity)(2)) // Deprecated
55 // ((Unit)(Unit)(3)) // Deprecated
56 ((Integer)(Integer)(4))
57 ((Unsigned)(Unsigned)(5))
58 ((String)(String)(6))
59 ((AttributeVector)(AttributeVector)(7))
60 );
61 * \endcode */
62
14/22
openstudio::AttributeValueType::buildStringVec[abi:cxx11](bool):
✓ Branch 0 taken 90 times.
✓ Branch 1 taken 492 times.
✓ Branch 3 taken 90 times.
✓ Branch 6 taken 90 times.
✗ Branch 7 not taken.
✓ Branch 9 taken 90 times.
✓ Branch 12 taken 90 times.
✓ Branch 17 taken 492 times.
✓ Branch 20 taken 492 times.
✓ Branch 23 taken 485 times.
✓ Branch 24 taken 194 times.
✓ Branch 25 taken 97 times.
✓ Branch 26 taken 97 times.
✗ Branch 27 not taken.
✓ Branch 28 taken 97 times.
openstudio::AttributeValueType::enumName[abi:cxx11]():
✓ Branch 1 taken 1 time.
openstudio::operator<<(std::ostream&, openstudio::AttributeValueType const&):
✗ Branch 1 not taken.
✗ Branch 4 not taken.
✗ Branch 7 not taken.
✗ Branch 10 not taken.
✗ Branch 13 not taken.
✗ Branch 16 not taken.
5007 OPENSTUDIO_ENUM(AttributeValueType,
63 ((Boolean)(Boolean)(0))
64 ((Double)(Double)(1))
65 // ((Quantity)(Quantity)(2)) // Deprecated
66 // ((Unit)(Unit)(3)) // Deprecated
67 ((Integer)(Integer)(4))
68 ((Unsigned)(Unsigned)(5))
69 ((String)(String)(6))
70 ((AttributeVector)(AttributeVector)(7))
71 );
72
73 // clang-format on
74
75 /** AttributeDescription describes what an acceptable Attribute is in a given context. At this
76 * time, it is primarily used in openstudio::analysis::GenericUncertaintyDescription. Note
77 * that AttributeDescription was designed to provide the information needed by a UI developer
78 * to properly prompt a user for the data needed to create a new Attribute. */
79 struct UTILITIES_API AttributeDescription
80 {
81 std::string name;
82 std::string displayName;
83 std::string description;
84 std::vector<AttributeValueType> validValueTypes;
85 bool required;
86 OSAttributeVariant defaultValue;
87
88 AttributeDescription(const std::string& t_name, const std::string& t_displayName, const std::string& t_description,
89 const AttributeValueType& t_validValueType, bool t_required);
90
91 AttributeDescription(const std::string& t_name, const std::string& t_displayName, const std::string& t_description,
92 const AttributeValueType& t_validValueType, bool t_required, OSAttributeVariant t_defaultValue);
93
94 AttributeDescription(const std::string& t_name, const std::string& t_displayName, const std::string& t_description,
95 const std::vector<AttributeValueType>& t_validValueTypes, bool t_required);
96
97 AttributeDescription(const std::string& t_name, const std::string& t_displayName, const std::string& t_description,
98 const std::vector<AttributeValueType>& t_validValueTypes, bool t_required, OSAttributeVariant t_defaultValue);
99 };
100
101 /** \relates AttributeDescription */
102 using OptionalAttributeDescription = boost::optional<AttributeDescription>;
103
104 /** \relates AttributeDescription */
105 using AttributeDescriptionVector = std::vector<AttributeDescription>;
106
107 /** An attribute is a name value pair where the value can be a bool, double, int,
108 * string, or vector of other attributes. The ability for an attribute value
109 * to be a vector of other attributes allows for flexible, hierarchical structures.
110 * Our convention is that attributes which correspond to plain old data (int, string, etc)
111 * are named in lower camel case, this corresponds to a member or variable name. Attributes
112 * of vector type are named in upper camel case to correspond to a class or struct name.
113 */
114 class UTILITIES_API Attribute
115 {
116 public:
117 using ImplType = detail::Attribute_Impl;
118
119 /// constructors
120
121 // AttributeValueType::Boolean
122 Attribute(const std::string& name, bool value);
123 Attribute(const std::string& name, bool value, const std::string& units);
124 Attribute(const std::string& name, bool value, const boost::optional<std::string>& units);
125 Attribute(const openstudio::UUID& uuid, const openstudio::UUID& versionUUID, const std::string& name,
126 const boost::optional<std::string>& displayName, bool value, const boost::optional<std::string>& units,
127 const std::string& source = std::string());
128
129 // AttributeValueType::Double
130 Attribute(const std::string& name, double value);
131 Attribute(const std::string& name, double value, const std::string& units);
132 Attribute(const std::string& name, double value, const boost::optional<std::string>& units);
133 Attribute(const openstudio::UUID& uuid, const openstudio::UUID& versionUUID, const std::string& name,
134 const boost::optional<std::string>& displayName, double value, const boost::optional<std::string>& units,
135 const std::string& source = std::string());
136
137 // AttributeValueType::Integer
138 Attribute(const std::string& name, int value);
139 Attribute(const std::string& name, int value, const std::string& units);
140 Attribute(const std::string& name, int value, const boost::optional<std::string>& units);
141 Attribute(const openstudio::UUID& uuid, const openstudio::UUID& versionUUID, const std::string& name,
142 const boost::optional<std::string>& displayName, int value, const boost::optional<std::string>& units,
143 const std::string& source = std::string());
144
145 // AttributeValueType::Unsigned
146 Attribute(const std::string& name, unsigned value);
147 Attribute(const std::string& name, unsigned value, const std::string& units);
148 Attribute(const std::string& name, unsigned value, const boost::optional<std::string>& units);
149 Attribute(const openstudio::UUID& uuid, const openstudio::UUID& versionUUID, const std::string& name,
150 const boost::optional<std::string>& displayName, unsigned value, const boost::optional<std::string>& units,
151 const std::string& source = std::string());
152
153 // AttributeValueType::String
154 // Const char overload is needed because otherwise it'll resolve to the bool constructor (implicit conversion of pointer to bool)
155 Attribute(const std::string& name, const char* value);
156 Attribute(const std::string& name, const char* value, const std::string& units);
157 Attribute(const std::string& name, const char* value, const boost::optional<std::string>& units);
158 Attribute(const openstudio::UUID& uuid, const openstudio::UUID& versionUUID, const std::string& name,
159 const boost::optional<std::string>& displayName, const char* value, const boost::optional<std::string>& units,
160 const std::string& source = std::string());
161
162 Attribute(const std::string& name, const std::string& value);
163 Attribute(const std::string& name, const std::string& value, const std::string& units);
164 Attribute(const std::string& name, const std::string& value, const boost::optional<std::string>& units);
165 Attribute(const openstudio::UUID& uuid, const openstudio::UUID& versionUUID, const std::string& name,
166 const boost::optional<std::string>& displayName, const std::string& value, const boost::optional<std::string>& units,
167 const std::string& source = std::string());
168
169 // AttributeValueType::AttributeVector
170 Attribute(const std::string& name, const std::vector<openstudio::Attribute>& value);
171 Attribute(const std::string& name, const std::vector<openstudio::Attribute>& value, const std::string& units);
172 Attribute(const std::string& name, const std::vector<openstudio::Attribute>& value, const boost::optional<std::string>& units);
173 Attribute(const openstudio::UUID& uuid, const openstudio::UUID& versionUUID, const std::string& name,
174 const boost::optional<std::string>& displayName, const std::vector<openstudio::Attribute>& value,
175 const boost::optional<std::string>& units, const std::string& source = std::string());
176
177 // Destructor
178 29382 virtual ~Attribute() = default;
179
180 // constructor from xml, throws if required arguments are missing
181 explicit Attribute(const pugi::xml_node& element);
182
183 Attribute(const Attribute& other);
184
185 Attribute clone() const;
186
187 // TODO: keep both? Keep public?
188 /// static constructor from xml
189 static boost::optional<Attribute> loadFromXml(const openstudio::path& xmlPath);
190
191 openstudio::UUID uuid() const;
192
193 openstudio::UUID versionUUID() const;
194
195 /// get the name
196 std::string name() const;
197
198 /// get the display name. if returnName and the display name is empty, will return
199 /// name() instead.
200 boost::optional<std::string> displayName(bool returnName = false) const;
201
202 /// set the display name
203 bool setDisplayName(const std::string& displayName);
204
205 /// clear the display name
206 void clearDisplayName();
207
208 /// get the (optional) data source
209 std::string source() const;
210
211 /// set the data source
212 void setSource(const std::string& source);
213
214 /// clear the data source
215 void clearSource();
216
217 /// get the attribute value type
218 AttributeValueType valueType() const;
219
220 /** Returns true if this Attribute value has been set. */
221 bool hasValue() const;
222
223 /// get value as a bool
224 bool valueAsBoolean() const;
225
226 /// set value. throws if wrong type.
227 void setValue(bool value);
228
229 /// get value as int
230 int valueAsInteger() const;
231
232 /// set value. throws if wrong type.
233 void setValue(int value);
234
235 /// get value as unsigned
236 unsigned valueAsUnsigned() const;
237
238 /// set value. throws if wrong type.
239 void setValue(unsigned value);
240
241 /// get value as double
242 double valueAsDouble() const;
243
244 /// set value. throws if wrong type.
245 void setValue(double value);
246
247 /// get value as string
248 std::string valueAsString() const;
249
250 /// set value. throws if wrong type.
251 void setValue(const char* value);
252
253 /// set value. throws if wrong type.
254 void setValue(const std::string& value);
255
256 /// get value as attribute vector
257 std::vector<Attribute> valueAsAttributeVector() const;
258
259 /// set value. throws if wrong type.
260 void setValue(const std::vector<Attribute>& value);
261
262 /// find child attribute by name
263 boost::optional<Attribute> findChildByName(const std::string& name) const;
264
265 /// get the units
266 boost::optional<std::string> units() const;
267
268 /// set the units
269 bool setUnits(const std::string& units);
270
271 /** If attribute is a simple type (non-vector), prints attribute's value to std::string as
272 * simply as possible. Numeric types print in high precision. Attribute vectors are printed
273 * as XML. */
274 std::string toString() const;
275
276 /// write object and all children out as xml to path.
277 bool saveToXml(const openstudio::path& path) const;
278
279 /// comparison
280 bool operator==(const Attribute& other) const;
281
282 /// cast to type T, can throw std::bad_cast
283 template <typename T>
284 T cast() const {
285 std::shared_ptr<typename T::ImplType> impl = this->getImpl<typename T::ImplType>();
286 if (!impl) {
287 throw(std::bad_cast());
288 }
289 return T(std::move(impl));
290 }
291
292 /// cast to optional of type T
293 template <typename T>
294 boost::optional<T> optionalCast() const {
295 boost::optional<T> result;
296 std::shared_ptr<typename T::ImplType> impl = this->getImpl<typename T::ImplType>();
297 if (impl) {
298 result = T(std::move(impl));
299 }
300 return result;
301 }
302
303 // short_version: if false, will include the uuid, versionuuid and source (if any)
304 Json::Value toJSON(bool short_version = true) const;
305 std::string toJSONString() const;
306
307 // Just the value as a Json::Value
308 Json::Value valueAsJSON() const;
309
310 protected:
311 UTILITIES_API friend std::ostream& operator<<(std::ostream& os, const Attribute& attribute);
312 // TODO: remove from public API or make protected/private
313 /// write object and all children to xml
314 pugi::xml_document toXml() const;
315
316 friend class detail::Attribute_Impl;
317 friend class EndUses;
318
319 // constructor from impl
320 Attribute(const std::shared_ptr<detail::Attribute_Impl>& impl);
321
322 /// get the impl
323 template <typename T>
324 11 std::shared_ptr<T> getImpl() const {
325 11 return std::dynamic_pointer_cast<T>(m_impl);
326 }
327
328 private:
329 − REGISTER_LOGGER("openstudio.Attribute");
330
331 std::shared_ptr<detail::Attribute_Impl> m_impl;
332 };
333
334 /** \relates Attribute */
335 using OptionalAttribute = boost::optional<Attribute>;
336
337 /** \relates Attribute */
338 using AttributeVector = std::vector<Attribute>;
339
340 /** Prints Attribute XML to os. \relates Attribute */
341 UTILITIES_API std::ostream& operator<<(std::ostream& os, const Attribute& attribute);
342
343 /** \relates Attribute */
344 // DLM: can this be a member of Attribute?
345 UTILITIES_API Attribute createAttributeFromVector(const std::string& name, const std::vector<int>& value);
346
347 /** \relates Attribute */
348 // DLM: can this be a member of Attribute?
349 UTILITIES_API Attribute createAttributeFromVector(const std::string& name, const std::vector<double>& value);
350
351 /** \relates Attribute */
352 // DLM: can this be a member of Attribute?
353 UTILITIES_API std::vector<int> getIntVectorFromAttribute(const Attribute& attribute);
354
355 /** \relates Attribute */
356 // DLM: can this be a member of Attribute?
357 UTILITIES_API std::vector<double> getDoubleVectorFromAttribute(const Attribute& attribute);
358
359 } // namespace openstudio
360
361 #endif // UTILITIES_DATA_ATTRIBUTE_HPP
362