OpenStudio:utilities
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Pages
Related Functions | List of all members
openstudio::Unit Class Reference

#include <Unit.hpp>

+ Inheritance diagram for openstudio::Unit:

Public Member Functions

Constructors and Destructors
 Unit (int scaleExponent=0, const std::string &prettyString="")
 Default constructor. More...
 
 Unit (const std::string &scaleAbbreviation, const std::string &prettyString="")
 Constructor using scale abbreviations registered in ScaleFactory. More...
 
virtual ~Unit ()=default
 
Unit clone () const
 Deep copy constructor. More...
 
Unit cloneToMixed () const
 Deep copy constructor that discards system designation. More...
 
Base Units and Scale
std::vector< std::string > baseUnits () const
 Returns base units already available in Unit. More...
 
bool isBaseUnit (const std::string &baseUnit) const
 Returns true if baseUnit is available in Unit. More...
 
int baseUnitExponent (const std::string &baseUnit) const
 Base unit exponent getter. Returns 0 if baseUnit not present. */. More...
 
void setBaseUnitExponent (const std::string &baseUnit, int exponent)
 Sets baseUnit^exponent. If baseUnit not yet present, is added and return value is true. More...
 
Scale scale () const
 Scale getter. More...
 
bool setScale (int scaleExponent)
 Sets the scale to the one registered in ScaleFactory for 10^scaleExponent. More...
 
bool setScale (const std::string &scaleAbbreviation)
 Sets the scale to the one registered in ScaleFactory under scaleAbbreviation. More...
 
Serialization
std::string standardString (bool withScale=true) const
 Returns the standard output string for this unit. More...
 
std::string prettyString (bool withScale=true) const
 Returns the preferred output string for this unit. More...
 
void setPrettyString (const std::string &str)
 Setter for prettyString (do not include scale abbreviation). More...
 
std::string print (bool withScale=true) const
 Returns prettyString(withScale) if it exists; otherwise returns standardString(withScale). More...
 
Unit System
UnitSystem system () const
 Getter for this Unit's system. More...
 
Mathematical Operators
bool operator== (const Unit &rUnit) const
 Equality for units. More...
 
Unitoperator*= (const Unit &rUnit)
 Multiply-assign operator. More...
 
Unitoperator/= (const Unit &rUnit)
 Divide-assign operator. More...
 
Unitpow (int expNum, int expDenom=1, bool okToCallFactory=true)
 Raise Unit to a rational power. More...
 
Type Casting
template<typename T >
cast () const
 Cast to type T. More...
 
template<typename T >
boost::optional< T > optionalCast () const
 Cast to boost::optional<T>. More...
 

Related Functions

(Note that these are not member functions.)

using OptionalUnit = boost::optional< Unit >
 
using UnitVector = std::vector< Unit >
 

Detailed Description

Base class that holds unit information in the form of (string,exponent) pairs.

The strings are called baseUnits and are typically the standard abbreviations such as "m", "ft", "kg", etc. Unit currently only supports integer exponents.

Related functions and operators are defined in Unit.hpp.

Constructor & Destructor Documentation

openstudio::Unit::Unit ( int  scaleExponent = 0,
const std::string &  prettyString = "" 
)

Default constructor.

Can set non-zero exponent (base 10) for the scale, and prettyString (alias for standardString, as in J = kg*m^2/s^2). The actual scale stored with Unit depends on what scales are registered in ScaleFactory. Throws if there is no entry for scaleExponent in ScaleFactory. Example:

openstudio::Unit u(-2,"J");
u.setBaseUnitExponent("kg",1);
u.setBaseUnitExponent("m",2);
u.setBaseUnitExponent("s",-2);
std::cout << u; // would print cJ, using default openstudio::ScaleFactory initialization 

Note that this is not the preferred method for constructing Joules. See openstudio::SIUnit, and openstudio::UnitFactory for alternatives.

openstudio::Unit::Unit ( const std::string &  scaleAbbreviation,
const std::string &  prettyString = "" 
)

Constructor using scale abbreviations registered in ScaleFactory.

For instance, pass in "k" to access kilo = 10^3 (using the default ScaleFactory initialization). Throws if there is no entry for scaleAbbreviation in ScaleFactory.

virtual openstudio::Unit::~Unit ( )
virtualdefault

Member Function Documentation

int openstudio::Unit::baseUnitExponent ( const std::string &  baseUnit) const

Base unit exponent getter. Returns 0 if baseUnit not present. */.

std::vector<std::string> openstudio::Unit::baseUnits ( ) const

Returns base units already available in Unit.

template<typename T >
T openstudio::Unit::cast ( ) const
inline

Cast to type T.

Throws std::bad_cast if object is not a T.

Unit openstudio::Unit::clone ( ) const

Deep copy constructor.

Unit openstudio::Unit::cloneToMixed ( ) const

Deep copy constructor that discards system designation.

Postcondition: system() == UnitSystem::Mixed.

bool openstudio::Unit::isBaseUnit ( const std::string &  baseUnit) const

Returns true if baseUnit is available in Unit.

Unit& openstudio::Unit::operator*= ( const Unit rUnit)

Multiply-assign operator.

Adds exponents on baseUnits and scales. Returned scale exponent may differ from expectation based on initialization of openstudio::ScaleFactory, see Scale operators declared in ScaleFactory.hpp.

Unit& openstudio::Unit::operator/= ( const Unit rUnit)

Divide-assign operator.

Subtracts exponents on rUnit's baseUnits and scales from lUnits's. Returned scale exponent may differ from expectation based on initialization of openstudio::ScaleFactory, see Scale operators declared in ScaleFactory.hpp.

bool openstudio::Unit::operator== ( const Unit rUnit) const

Equality for units.

Does not require identical systems, scales, or prettyStrings.

template<typename T >
boost::optional<T> openstudio::Unit::optionalCast ( ) const
inline

Cast to boost::optional<T>.

Return value is boost::none (evaluates to false) if object is not a T.

Unit& openstudio::Unit::pow ( int  expNum,
int  expDenom = 1,
bool  okToCallFactory = true 
)

Raise Unit to a rational power.

Throws openstudio::Exception if expDenom is not a common divisor for all baseUnit and scale exponents. Returned scale exponent may differ from expectation based on initialization of openstudio::ScaleFactory, see Scale operators declared in ScaleFactory.hpp.

std::string openstudio::Unit::prettyString ( bool  withScale = true) const

Returns the preferred output string for this unit.

For instance, the prettyString for SI energy is 'J' for Joules, but the standard string is 'kg*m^2/s^2'.

If withScale==true (the default since this is probably preferred by users), scale abbreviation is prefixed. Prefers km^2 to M(m^2), kBtu/ft^2 to k(Btu/ft^2).

std::string openstudio::Unit::print ( bool  withScale = true) const

Returns prettyString(withScale) if it exists; otherwise returns standardString(withScale).

Scale openstudio::Unit::scale ( ) const

Scale getter.

void openstudio::Unit::setBaseUnitExponent ( const std::string &  baseUnit,
int  exponent 
)

Sets baseUnit^exponent. If baseUnit not yet present, is added and return value is true.

void openstudio::Unit::setPrettyString ( const std::string &  str)

Setter for prettyString (do not include scale abbreviation).

openstudio::Unit attempts to keep up with prettyStrings, but makes no promises. Precondition: isCompoundUnit(str). Otherwise throws.

bool openstudio::Unit::setScale ( int  scaleExponent)

Sets the scale to the one registered in ScaleFactory for 10^scaleExponent.

Returns true if successful, false if no Scale with exponent == scaleExponent exists in ScaleFactory. In that case, Unit remains unchanged.

bool openstudio::Unit::setScale ( const std::string &  scaleAbbreviation)

Sets the scale to the one registered in ScaleFactory under scaleAbbreviation.

Returns true if successful, false if no Scale with abbr == scaleAbbreviation exists in ScaleFactory. In that case, Unit remains unchanged.

std::string openstudio::Unit::standardString ( bool  withScale = true) const

Returns the standard output string for this unit.

Version withScale==false is used as a signature elsewhere in the utility. LaTeX formatting is used. Examples of valid strings:

  • kg*m/s^2
  • Btu/h

Units with positive exponents come first, then '/', then units with negative exponents. ^ indicates a non-unity exponent.

If withScale==true (the default since this is probably preferred by users), scale abbreviation is prefixed. Prefers km^2 to M(m^2), kBtu/ft^2 to k(Btu/ft^2).

UnitSystem openstudio::Unit::system ( ) const

Getter for this Unit's system.

Friends And Related Function Documentation

using OptionalUnit = boost::optional<Unit>
related
using UnitVector = std::vector<Unit>
related