OpenStudio:utilities
 AllClasses Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Pages

#include "Unit.hpp"

Inheritance diagram for openstudio::Unit:

Public Member Functions

 Unit (int scaleExponent=0, const std::string &prettyString="")
 Unit (const std::string &scaleAbbreviation, const std::string &prettyString="")
virtual ~Unit ()
Unit clone () const
Unit cloneToMixed () const
std::vector< std::string > baseUnits () const
bool isBaseUnit (const std::string &baseUnit) const
int baseUnitExponent (const std::string &baseUnit) const
void setBaseUnitExponent (const std::string &baseUnit, int exponent)
Scale scale () const
bool setScale (int scaleExponent)
bool setScale (const std::string &scaleAbbreviation)
std::string standardString (bool withScale=true) const
std::string prettyString (bool withScale=true) const
void setPrettyString (const std::string &str)
std::string print (bool withScale=true) const
UnitSystem system () const
bool operator== (const Unit &rUnit) const
Unitoperator*= (const Unit &rUnit)
Unitoperator/= (const Unit &rUnit)
Unitpow (int expNum, int expDenom=1, bool okToCallFactory=true)
template<typename T >
cast () const
template<typename T >
boost::optional< T > optionalCast () const

Related Functions

typedef boost::optional< UnitOptionalUnit
typedef std::vector< UnitUnitVector

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 ( )
inlinevirtual

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

typedef boost::optional<Unit> OptionalUnit
related
typedef std::vector<Unit> UnitVector
related