GCC Code Coverage Report


Directory: ./
Coverage: low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%
Coverage Exec / Excl / Total
Lines: 56.1% 97 / 0 / 173
Functions: 59.5% 25 / 0 / 42
Branches: 46.9% 46 / 0 / 98

src/utilities/units/Unit.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_UNITS_UNIT_HPP
7 #define UTILITIES_UNITS_UNIT_HPP
8
9 #include "../UtilitiesAPI.hpp"
10
11 #include "../core/Logger.hpp"
12 #include "../core/Enum.hpp"
13
14 #include <boost/smart_ptr.hpp>
15 #include <boost/optional.hpp>
16
17 #include <vector>
18 #include <string>
19 #include <iostream>
20
21 namespace openstudio {
22
23 struct Scale;
24
25 namespace detail {
26
27 class Unit_Impl;
28
29 } // namespace detail
30
31 // clang-format off
32
33 /** \class UnitSystem
34 * \brief Unit systems supported by OpenStudio's runtime units utility.
35 * \details See the OPENSTUDIO_ENUM documentation in utilities/core/Enum.hpp.
36 * The actual macro call is:
37 * \code
38 OPENSTUDIO_ENUM(UnitSystem,
39 ((Mixed))
40 ((SI))
41 ((IP))
42 ((BTU))
43 ((CFM))
44 ((GPD))
45 ((MPH))
46 ((Wh))
47 ((Therm))
48 ((Misc1))
49 ((Celsius))
50 ((Fahrenheit))
51 );
52 * \endcode
53 * \relates Unit */
54
8/22
openstudio::UnitSystem::buildStringVec[abi:cxx11](bool):
✗ Branch 0 not taken.
✓ Branch 1 taken 22632 times.
✗ Branch 3 not taken.
✗ Branch 6 not taken.
✗ Branch 7 not taken.
✗ Branch 9 not taken.
✗ Branch 12 not taken.
✓ Branch 17 taken 22632 times.
✓ Branch 20 taken 22632 times.
✓ Branch 23 taken 20746 times.
✓ Branch 24 taken 3772 times.
✓ Branch 25 taken 1886 times.
✓ Branch 26 taken 1886 times.
✗ Branch 27 not taken.
✓ Branch 28 taken 1886 times.
openstudio::UnitSystem::enumName[abi:cxx11]():
✗ Branch 1 not taken.
openstudio::operator<<(std::ostream&, openstudio::UnitSystem 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.
324891 OPENSTUDIO_ENUM(UnitSystem,
55 ((Mixed))
56 ((SI))
57 ((IP))
58 ((BTU))
59 ((CFM))
60 ((GPD))
61 ((MPH))
62 ((Wh))
63 ((Therm))
64 ((Misc1))
65 ((Celsius))
66 ((Fahrenheit))
67 );
68
69 // clang-format on
70
71 /** Base class that holds unit information in the form of (string,exponent) pairs. The
72 * strings are called baseUnits and are typically the standard abbreviations such as
73 * "m", "ft", "kg", etc. Unit currently only supports integer exponents.
74 *
75 * Related functions and operators are defined in Unit.hpp. */
76 class UTILITIES_API Unit
77 {
78 public:
79 /** @name Constructors and Destructors */
80 //@{
81
82 /** Default constructor. Can set non-zero exponent (base 10) for the scale, and prettyString
83 * (alias for standardString, as in J = kg*m^2/s^2). The actual scale stored with Unit depends
84 * on what scales are registered in ScaleFactory. Throws if there is no entry for
85 * scaleExponent in ScaleFactory. Example: \verbatim
86 openstudio::Unit u(-2,"J");
87 u.setBaseUnitExponent("kg",1);
88 u.setBaseUnitExponent("m",2);
89 u.setBaseUnitExponent("s",-2);
90 std::cout << u; // would print cJ, using default openstudio::ScaleFactory initialization \endverbatim
91 * Note that this is not the preferred method for constructing Joules. See openstudio::SIUnit,
92 * and openstudio::UnitFactory for alternatives. */
93 Unit(int scaleExponent = 0, const std::string& prettyString = "");
94
95 /** Constructor using scale abbreviations registered in ScaleFactory. For instance, pass
96 * in "k" to access kilo = 10^3 (using the default ScaleFactory initialization). Throws if
97 * there is no entry for scaleAbbreviation in ScaleFactory. */
98 Unit(const std::string& scaleAbbreviation, const std::string& prettyString = "");
99
100 5264776 virtual ~Unit() = default;
101
102 /** Deep copy constructor. */
103 Unit clone() const;
104
105 /** Deep copy constructor that discards system designation. Postcondition: system() == UnitSystem::Mixed. */
106 Unit cloneToMixed() const;
107
108 //@}
109 /** @name Base Units and Scale */
110 //@{
111
112 /// Returns base units already available in Unit.
113 std::vector<std::string> baseUnits() const;
114
115 /// Returns true if baseUnit is available in Unit.
116 bool isBaseUnit(const std::string& baseUnit) const;
117
118 /// Base unit exponent getter. Returns 0 if baseUnit not present. */
119 int baseUnitExponent(const std::string& baseUnit) const;
120
121 /// Sets baseUnit^exponent. If baseUnit not yet present, is added and return value is true.
122 // cppcheck-suppress functionConst
123 void setBaseUnitExponent(const std::string& baseUnit, int exponent);
124
125 /// Scale getter.
126 Scale scale() const;
127
128 /** Sets the scale to the one registered in ScaleFactory for 10^scaleExponent. Returns true
129 * if successful, false if no Scale with exponent == scaleExponent exists in ScaleFactory.
130 * In that case, Unit remains unchanged. */
131 // cppcheck-suppress functionConst
132 bool setScale(int scaleExponent);
133
134 /** Sets the scale to the one registered in ScaleFactory under scaleAbbreviation. Returns true
135 * if successful, false if no Scale with abbr == scaleAbbreviation exists in ScaleFactory.
136 * In that case, Unit remains unchanged. */
137 // cppcheck-suppress functionConst
138 bool setScale(const std::string& scaleAbbreviation);
139
140 //@}
141 /** @name Serialization */
142 //@{
143
144 /** Returns the standard output string for this unit. Version withScale==false is used as a
145 * signature elsewhere in the utility. LaTeX formatting is used. Examples of valid strings:
146 *
147 * <ul>
148 * <li>kg*m/s^2</li>
149 * <li>Btu/h</li>
150 * </ul>
151 *
152 * Units with positive exponents come first, then '/', then units with negative exponents.
153 * ^ indicates a non-unity exponent.
154 *
155 * If withScale==true (the default since this is probably preferred by users), scale
156 * abbreviation is prefixed. Prefers km^2 to M(m^2), kBtu/ft^2 to k(Btu/ft^2).
157 */
158 std::string standardString(bool withScale = true) const;
159
160 /** Returns the preferred output string for this unit. For instance, the prettyString
161 * for SI energy is 'J' for Joules, but the standard string is 'kg*m^2/s^2'.
162 *
163 * If withScale==true (the default since this is probably preferred by users), scale
164 * abbreviation is prefixed. Prefers km^2 to M(m^2), kBtu/ft^2 to k(Btu/ft^2). */
165 std::string prettyString(bool withScale = true) const;
166
167 /** Setter for prettyString (do not include scale abbreviation). openstudio::Unit attempts
168 * to keep up with prettyStrings, but makes no promises. Precondition: isCompoundUnit(str).
169 * Otherwise throws. */
170 // cppcheck-suppress functionConst
171 void setPrettyString(const std::string& str);
172
173 /** Returns prettyString(withScale) if it exists; otherwise returns standardString(withScale). */
174 std::string print(bool withScale = true) const;
175
176 //@}
177 /** @name Unit System */
178 //@{
179
180 /** Getter for this Unit's system */
181 UnitSystem system() const;
182
183 //@}
184 /** @name Mathematical Operators */
185 //@{
186
187 /** Equality for units. Does not require identical systems, scales, or prettyStrings. */
188 bool operator==(const Unit& rUnit) const;
189
190 /** Multiply-assign operator. Adds exponents on baseUnits and scales. Returned scale exponent
191 * may differ from expectation based on initialization of openstudio::ScaleFactory, see
192 * Scale operators declared in ScaleFactory.hpp. */
193 Unit& operator*=(const Unit& rUnit);
194
195 /** Divide-assign operator. Subtracts exponents on rUnit's baseUnits and scales from lUnits's.
196 * Returned scale exponent may differ from expectation based on initialization of
197 * openstudio::ScaleFactory, see Scale operators declared in ScaleFactory.hpp. */
198 Unit& operator/=(const Unit& rUnit);
199
200 /** Raise Unit to a rational power. Throws openstudio::Exception if expDenom is not a common divisor
201 * for all baseUnit and scale exponents. Returned scale exponent may differ from expectation
202 * based on initialization of openstudio::ScaleFactory, see Scale operators declared in
203 * ScaleFactory.hpp. */
204 Unit& pow(int expNum, int expDenom = 1, bool okToCallFactory = true);
205
206 //@}
207 /** @name Type Casting */
208 //@{
209
210 /** Get the impl pointer */
211 template <typename T>
212 6220899 std::shared_ptr<T> getImpl() const {
213 6220899 return std::dynamic_pointer_cast<T>(m_impl);
214 }
215
216 /** Cast to type T. Throws std::bad_cast if object is not a T. */
217 template <typename T>
218 2510427 T cast() const {
219 2510427 std::shared_ptr<typename T::ImplType> impl = this->getImpl<typename T::ImplType>();
220
10/16
openstudio::BTUUnit openstudio::Unit::cast<openstudio::BTUUnit>() const:
✗ Branch 1 not taken.
✓ Branch 2 taken 4 times.
openstudio::CFMUnit openstudio::Unit::cast<openstudio::CFMUnit>() const:
✗ Branch 1 not taken.
✓ Branch 2 taken 1 time.
openstudio::CelsiusUnit openstudio::Unit::cast<openstudio::CelsiusUnit>() const:
✓ Branch 1 taken 1 time.
✓ Branch 2 taken 1 time.
openstudio::FahrenheitUnit openstudio::Unit::cast<openstudio::FahrenheitUnit>() const:
✗ Branch 1 not taken.
✓ Branch 2 taken 1 time.
openstudio::IPUnit openstudio::Unit::cast<openstudio::IPUnit>() const:
✗ Branch 1 not taken.
✓ Branch 2 taken 40 times.
openstudio::SIUnit openstudio::Unit::cast<openstudio::SIUnit>() const:
✓ Branch 1 taken 1 time.
✓ Branch 2 taken 7 times.
openstudio::TemperatureUnit openstudio::Unit::cast<openstudio::TemperatureUnit>() const:
✗ Branch 1 not taken.
✓ Branch 2 taken 1460 times.
openstudio::Unit openstudio::Unit::cast<openstudio::Unit>() const:
✗ Branch 1 not taken.
✓ Branch 2 taken 2508911 times.
2510427 if (!impl) {
221 2 throw(std::bad_cast());
222 }
223
8/8
openstudio::BTUUnit openstudio::Unit::cast<openstudio::BTUUnit>() const:
✓ Branch 3 taken 4 times.
openstudio::CFMUnit openstudio::Unit::cast<openstudio::CFMUnit>() const:
✓ Branch 3 taken 1 time.
openstudio::CelsiusUnit openstudio::Unit::cast<openstudio::CelsiusUnit>() const:
✓ Branch 3 taken 1 time.
openstudio::FahrenheitUnit openstudio::Unit::cast<openstudio::FahrenheitUnit>() const:
✓ Branch 3 taken 1 time.
openstudio::IPUnit openstudio::Unit::cast<openstudio::IPUnit>() const:
✓ Branch 3 taken 40 times.
openstudio::SIUnit openstudio::Unit::cast<openstudio::SIUnit>() const:
✓ Branch 3 taken 7 times.
openstudio::TemperatureUnit openstudio::Unit::cast<openstudio::TemperatureUnit>() const:
✓ Branch 3 taken 1460 times.
openstudio::Unit openstudio::Unit::cast<openstudio::Unit>() const:
✓ Branch 3 taken 2508911 times.
5020850 return T(std::move(impl));
224 2510427 }
225
226 /** Cast to boost::optional<T>. Return value is boost::none (evaluates to false)
227 * if object is not a T. */
228 template <typename T>
229 11009 boost::optional<T> optionalCast() const {
230 11009 boost::optional<T> result;
231 11009 std::shared_ptr<typename T::ImplType> impl = this->getImpl<typename T::ImplType>();
232
10/26
boost::optional<openstudio::BTUUnit> openstudio::Unit::optionalCast<openstudio::BTUUnit>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
boost::optional<openstudio::CFMUnit> openstudio::Unit::optionalCast<openstudio::CFMUnit>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
boost::optional<openstudio::CelsiusUnit> openstudio::Unit::optionalCast<openstudio::CelsiusUnit>() const:
✓ Branch 1 taken 1 time.
✓ Branch 2 taken 1 time.
boost::optional<openstudio::FahrenheitUnit> openstudio::Unit::optionalCast<openstudio::FahrenheitUnit>() const:
✓ Branch 1 taken 1 time.
✓ Branch 2 taken 1 time.
boost::optional<openstudio::GPDUnit> openstudio::Unit::optionalCast<openstudio::GPDUnit>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
boost::optional<openstudio::IPUnit> openstudio::Unit::optionalCast<openstudio::IPUnit>() const:
✓ Branch 1 taken 39 times.
✓ Branch 2 taken 2 times.
boost::optional<openstudio::MPHUnit> openstudio::Unit::optionalCast<openstudio::MPHUnit>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
boost::optional<openstudio::Misc1Unit> openstudio::Unit::optionalCast<openstudio::Misc1Unit>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
boost::optional<openstudio::SIUnit> openstudio::Unit::optionalCast<openstudio::SIUnit>() const:
✓ Branch 1 taken 2 times.
✓ Branch 2 taken 1 time.
boost::optional<openstudio::TemperatureUnit> openstudio::Unit::optionalCast<openstudio::TemperatureUnit>() const:
✓ Branch 1 taken 1664 times.
✓ Branch 2 taken 9297 times.
boost::optional<openstudio::ThermUnit> openstudio::Unit::optionalCast<openstudio::ThermUnit>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
boost::optional<openstudio::Unit> openstudio::Unit::optionalCast<openstudio::Unit>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
boost::optional<openstudio::WhUnit> openstudio::Unit::optionalCast<openstudio::WhUnit>() const:
✗ Branch 1 not taken.
✗ Branch 2 not taken.
11009 if (impl) {
233
10/26
boost::optional<openstudio::BTUUnit> openstudio::Unit::optionalCast<openstudio::BTUUnit>() const:
✗ Branch 3 not taken.
✗ Branch 6 not taken.
boost::optional<openstudio::CFMUnit> openstudio::Unit::optionalCast<openstudio::CFMUnit>() const:
✗ Branch 3 not taken.
✗ Branch 6 not taken.
boost::optional<openstudio::CelsiusUnit> openstudio::Unit::optionalCast<openstudio::CelsiusUnit>() const:
✓ Branch 3 taken 1 time.
✓ Branch 6 taken 1 time.
boost::optional<openstudio::FahrenheitUnit> openstudio::Unit::optionalCast<openstudio::FahrenheitUnit>() const:
✓ Branch 3 taken 1 time.
✓ Branch 6 taken 1 time.
boost::optional<openstudio::GPDUnit> openstudio::Unit::optionalCast<openstudio::GPDUnit>() const:
✗ Branch 3 not taken.
✗ Branch 6 not taken.
boost::optional<openstudio::IPUnit> openstudio::Unit::optionalCast<openstudio::IPUnit>() const:
✓ Branch 3 taken 39 times.
✓ Branch 6 taken 39 times.
boost::optional<openstudio::MPHUnit> openstudio::Unit::optionalCast<openstudio::MPHUnit>() const:
✗ Branch 3 not taken.
✗ Branch 6 not taken.
boost::optional<openstudio::Misc1Unit> openstudio::Unit::optionalCast<openstudio::Misc1Unit>() const:
✗ Branch 3 not taken.
✗ Branch 6 not taken.
boost::optional<openstudio::SIUnit> openstudio::Unit::optionalCast<openstudio::SIUnit>() const:
✓ Branch 3 taken 2 times.
✓ Branch 6 taken 2 times.
boost::optional<openstudio::TemperatureUnit> openstudio::Unit::optionalCast<openstudio::TemperatureUnit>() const:
✓ Branch 3 taken 1664 times.
✓ Branch 6 taken 1664 times.
boost::optional<openstudio::ThermUnit> openstudio::Unit::optionalCast<openstudio::ThermUnit>() const:
✗ Branch 3 not taken.
✗ Branch 6 not taken.
boost::optional<openstudio::Unit> openstudio::Unit::optionalCast<openstudio::Unit>() const:
✗ Branch 3 not taken.
✗ Branch 6 not taken.
boost::optional<openstudio::WhUnit> openstudio::Unit::optionalCast<openstudio::WhUnit>() const:
✗ Branch 3 not taken.
✗ Branch 6 not taken.
1707 result = T(std::move(impl));
234 }
235 22018 return result;
236 11009 }
237
238 //@}
239 protected:
240 /// @cond
241 using ImplType = detail::Unit_Impl;
242
243 explicit Unit(std::shared_ptr<detail::Unit_Impl> impl);
244
245 friend class detail::Unit_Impl;
246
247 /// @endcond
248 private:
249 std::shared_ptr<detail::Unit_Impl> m_impl;
250
251 REGISTER_LOGGER("openstudio.units.Unit");
252 };
253
254 /** \relates Unit*/
255 using OptionalUnit = boost::optional<Unit>;
256
257 /** \relates Unit*/
258 using UnitVector = std::vector<Unit>;
259
260 /** Print u to a stream. Scale abbreviation, if any, is printed before prettyString (if
261 * non-empty) or standardString. */
262 UTILITIES_API std::ostream& operator<<(std::ostream& os, const Unit& u);
263
264 /** Parses unit string into a Unit object. Precondition: isUnit == true. Otherwise, throws.
265 * Be forewarned--this does dumb parsing. Doesn't work to extract scales from expressions
266 * like "kN", doesn't match base units up with unit systems.
267 *
268 * Postcondition: prettyString() == "".
269 * \sa UnitFactory */
270 UTILITIES_API Unit parseUnitString(const std::string& unitString);
271
272 /** Inequality for units. Does not compare scales or prettyStrings. */
273 UTILITIES_API bool operator!=(const Unit& lUnit, const Unit& rUnit);
274
275 /** Unit multiplication. Adds exponents on baseUnits and scales. Returned scale exponent
276 * may differ from expectation based on initialization of openstudio::ScaleFactory, see
277 * Scale operators declared in ScaleFactory.hpp. */
278 UTILITIES_API Unit operator*(const Unit& lUnit, const Unit& rUnit);
279
280 /** Unit division. Subtracts exponents on rUnit's baseUnits and scales from lUnits's.
281 * Returned scale exponent may differ from expectation based on initialization of
282 * openstudio::ScaleFactory, see Scale operators declared in ScaleFactory.hpp.*/
283 UTILITIES_API Unit operator/(const Unit& lUnit, const Unit& rUnit);
284
285 /** Calculate rUnit^(expNum/expDenom). Throws openstudio::Exception if expDenom is not a common divisor
286 * for all baseUnit and scale exponents. Returned scale exponent may differ from expectation
287 * based on initialization of openstudio::ScaleFactory, see Scale operators declared in
288 * ScaleFactory.hpp. */
289 UTILITIES_API Unit pow(const Unit& rUnit, int expNum, int expDenom = 1);
290
291 } // namespace openstudio
292
293 #endif // UTILITIES_UNITS_UNIT_HPP
294