OpenStudioCore:utilities
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Pages
Protected Types | Protected Member Functions | Related Functions | List of all members
openstudio::IdfObject Class Reference

#include <IdfObject.hpp>

+ Inheritance diagram for openstudio::IdfObject:

Public Member Functions

Constructors
 IdfObject (IddObjectType type, bool fastName=false)
 Constructor from type. More...
 
 IdfObject (const IddObject &, bool fastName=false)
 Constructor from iddObject. More...
 
 IdfObject (const IdfObject &other)
 Copy constructor. More...
 
virtual ~IdfObject ()
 
IdfObject clone (bool keepHandle=false) const
 Creates a deep copy of this object. More...
 
Getters
Handle handle () const
 Returns this object's handle, which is only valid in the containing Workspace. More...
 
IddObject iddObject () const
 Get this object's IddObject. More...
 
std::string comment () const
 Returns the comment block associated with the object. More...
 
boost::optional< std::string > fieldComment (unsigned index, bool returnDefault=false) const
 Returns the comment associated with field index, if one exists. More...
 
boost::optional< std::string > name (bool returnDefault=false) const
 Get the name of the object, if it exists. More...
 
std::string briefDescription () const
 Get a brief description of this object. More...
 
bool isEmpty (unsigned index) const
 Returns true if the field is empty. More...
 
boost::optional< std::string > getString (unsigned index, bool returnDefault=false, bool returnUninitializedEmpty=false) const
 Get the value of field index, if index < numFields(). More...
 
boost::optional< double > getDouble (unsigned index, bool returnDefault=false) const
 Get the value of the field at index, converted to double, if possible. More...
 
OSOptionalQuantity getQuantity (unsigned index, bool returnDefault=false, bool returnIP=false) const
 Returns the Quantity at index, if possible. More...
 
boost::optional< unsigned > getUnsigned (unsigned index, bool returnDefault=false) const
 Get the value of the field at index, converted to unsigned, if possible. More...
 
boost::optional< intgetInt (unsigned index, bool returnDefault=false) const
 Get value of the field at index, converted to int, if possible. More...
 
boost::optional< QUrl > getURL (unsigned index, bool returnDefault=false) const
 Get value of the field at index, converted to qurl, if possible. More...
 
IdfExtensibleGroup getExtensibleGroup (unsigned groupIndex) const
 Returns the IdfExtensibleGroup at groupIndex, if it exists. More...
 
std::vector< IdfExtensibleGroupextensibleGroups () const
 Returns this object's IdfExtensibleGroups. More...
 
Setters
void setComment (const std::string &msg)
 Sets the comment block associated with the object. More...
 
bool setFieldComment (unsigned index, const std::string &cmnt)
 Sets the comment associated with field index, if that field exists. More...
 
boost::optional< std::string > setName (const std::string &newName)
 Sets the name field if it exists, returning the actual name string set. More...
 
boost::optional< std::string > createName (bool overwrite=true)
 Sets the name field to a new, unique name, if the name field exists and (is empty or overwrite == true). More...
 
bool setString (unsigned index, const std::string &value)
 Sets the field at index to value, if possible. More...
 
bool setDouble (unsigned index, double value)
 Sets the field at index to value, if possible. More...
 
bool setQuantity (unsigned index, const Quantity &q)
 Sets the field at index to q, if possible. More...
 
bool setUnsigned (unsigned index, unsigned value)
 Sets the field at index to value, if possible. More...
 
bool setInt (unsigned index, int value)
 Sets the field at index to value, if possible. More...
 
IdfExtensibleGroup pushExtensibleGroup ()
 Pushes a new extensible group onto the object, if possible. More...
 
IdfExtensibleGroup pushExtensibleGroup (const std::vector< std::string > &values)
 Pushes a new extensible group onto the object, if possible. More...
 
IdfExtensibleGroup insertExtensibleGroup (unsigned groupIndex)
 Inserts a new extensible group at groupIndex, if possible. More...
 
IdfExtensibleGroup insertExtensibleGroup (unsigned groupIndex, const std::vector< std::string > &values)
 Inserts a new extensible group at groupIndex, if possible. More...
 
std::vector< std::string > popExtensibleGroup ()
 Pops the final extensible group from the object, if possible. More...
 
std::vector< std::string > eraseExtensibleGroup (unsigned groupIndex)
 Erases the extensible group at groupIndex, if possible. More...
 
std::vector< std::vector
< std::string > > 
clearExtensibleGroups ()
 Pops all IdfExtensibleGroups from the object, if possible. More...
 
Queries
unsigned numFields () const
 Returns the current number of fields (including extensible groups) in the object. More...
 
unsigned numNonextensibleFields () const
 Returns the current number of non-extensible fields in the object. More...
 
unsigned minFields () const
 Returns the minimum number of fields an object of this type must have to be valid. More...
 
boost::optional< unsigned > maxFields () const
 Returns the maximum number of fields an object of this type can have and still be valid. More...
 
unsigned numExtensibleGroups () const
 Returns the number of extensible groups in the object. More...
 
unsigned minExtensibleGroups () const
 Returns the minimum number of IdfExtensibleGroups an object of this type must have to be valid. More...
 
boost::optional< unsigned > maxExtensibleGroups () const
 Returns the maximum number of IdfExtensibleGroups an object of this type must have to be valid. More...
 
bool isObjectListField (unsigned index) const
 Returns true if index is in objectListFields(). More...
 
std::vector< unsigned > objectListFields () const
 Returns the indices of all fields that can point to other objects. More...
 
bool isDataField (unsigned index) const
 Returns true if index is in dataFields(). More...
 
std::vector< unsigned > dataFields () const
 Returns the indices of all fields that are not managedObjectListFields(). More...
 
std::vector< unsigned > requiredFields () const
 Returns the indices of all fields that are required, as defined by the IddObject. More...
 
bool isValid (StrictnessLevel level) const
 Returns true if this IdfObject is valid, that is, has no errors at or below level. More...
 
ValidityReport validityReport (StrictnessLevel level, bool checkNames=true) const
 Returns a ValidityReport for this IdfObject containing all errors at or below level. More...
 
bool dataFieldsEqual (const IdfObject &other) const
 Checks for equality of data (non-managedObjectList) fields. More...
 
bool objectListFieldsEqual (const IdfObject &other) const
 Checks for equality of objectListFields(). More...
 
bool objectListFieldsNonConflicting (const IdfObject &other) const
 Returns true if for all managedObjectListFields() that for both objects are non-empty, the values are equal (using the same criteria as objectListFieldsEqual). More...
 
bool operator== (const IdfObject &other) const
 Equality comparator for IdfObjects. More...
 
bool operator!= (const IdfObject &other) const
 Negation of operator==. More...
 
Type Casting
template<typename T >
cast () const
 cast to type T, can throw std::bad_cast More...
 
template<typename T >
boost::optional< T > optionalCast () const
 cast to optional of type T More...
 

Protected Types

typedef detail::IdfObject_Impl ImplType
 

Protected Member Functions

 IdfObject (std::shared_ptr< detail::IdfObject_Impl > impl)
 Protected constructor from impl. More...
 

Related Functions

(Note that these are not member functions.)

template<typename T , typename U >
std::vector< T > castVector (const std::vector< U > &objects)
 Helper function to cast a whole vector of objects. More...
 
template<typename T >
std::vector< Handle > getHandles (const std::vector< T > &objects)
 Helper function to get the handles of a vector of objects. More...
 
typedef std::pair< IdfObject,
IdfObject
IdfObjectPair
 
typedef std::vector< IdfObjectIdfObjectVector
 
std::ostream & operator<< (std::ostream &os, const IdfObject &IdfObject)
 
typedef boost::optional
< IdfObject
OptionalIdfObject
 
template<typename T , typename U >
std::vector< T > subsetCastVector (const std::vector< U > &original)
 Returns a subset of original cast to a new type, only keeping those objects for which the optionalCast is successful. More...
 

Serialization

std::ostream & print (std::ostream &os) const
 Serialize this object to os as Idf text. More...
 
std::ostream & printName (std::ostream &os, bool hasFields=true) const
 Serialize just the preceding comments and name of this IdfObject in the format used by full object print. More...
 
std::ostream & printField (std::ostream &os, unsigned index, bool isLastField=false) const
 Serialize field index in the format used by full object print. More...
 
static boost::optional< IdfObjectload (const std::string &text)
 Constructor from text. More...
 
static boost::optional< IdfObjectload (const std::string &text, const IddObject &iddObject)
 Constructor from text and an explicit iddObject. More...
 
static int printedFieldSpace ()
 Returns the width, in characters, of the default amount of space given to field data during printing. More...
 

Detailed Description

IdfObject holds and manipulates data in the EnergyPlus Idd/Idf format.

An IdfObject consists of an IddObject, which defines the IdfObject's data, some number of string fields (that must conform to the IddObject), and user comments. In text, an IdfObject follows the syntax of (with method calls replaced with their returned strings):

IdfObject.comment()
IddObject.name(),
IdfObject.getString(0), IdfObject.fieldComment(0)
IdfObject.getString(1), IdfObject.fieldComment(1)
...
IdfObject.getString(IdfObject.numFields()-1); IdfObject.fieldComment(IdfObject.numFields()-1)

IdfObject is shared, that is, on copy construction the original IdfObject and the new one share their data. If you want an unconnected IdfObject initialized with the same data, use .clone().

All fields are stored internally as text. Conversions to numeric types may not succeed.

Field indexing follows the C/C++ convention: 0, 1, ...

On its own, IdfObject maintains validity at enums::Strictness level None.

Member Typedef Documentation

typedef detail::IdfObject_Impl openstudio::IdfObject::ImplType
protected

Constructor & Destructor Documentation

openstudio::IdfObject::IdfObject ( IddObjectType  type,
bool  fastName = false 
)
explicit

Constructor from type.

Equivalent to IdfObject(IddFactory::instance.iddObject(type)), unless type == IddObjectType::UserCustom, in which case, the constructed object is equivalent to IdfObject(IddObjectType::Catchall). If fastName is true a UUID is assigned as the name, otherwise no name is assigned.

openstudio::IdfObject::IdfObject ( const IddObject ,
bool  fastName = false 
)
explicit

Constructor from iddObject.

If fastName is true a UUID is assigned as the name, otherwise no name is assigned.

openstudio::IdfObject::IdfObject ( const IdfObject other)

Copy constructor.

Shares data with other, so changes made by either copy affects the data of both.

virtual openstudio::IdfObject::~IdfObject ( )
inlinevirtual
openstudio::IdfObject::IdfObject ( std::shared_ptr< detail::IdfObject_Impl >  impl)
protected

Protected constructor from impl.

Member Function Documentation

std::string openstudio::IdfObject::briefDescription ( ) const

Get a brief description of this object.

Always includes iddObject().type(), and includes name() if available and not empty.

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

cast to type T, can throw std::bad_cast

std::vector<std::vector<std::string> > openstudio::IdfObject::clearExtensibleGroups ( )

Pops all IdfExtensibleGroups from the object, if possible.

Returns popped data if successful. Otherwise, the returned vector will be empty.

IdfObject openstudio::IdfObject::clone ( bool  keepHandle = false) const

Creates a deep copy of this object.

This object and the newly created object do not share data, and the new object is always unlocked.

std::string openstudio::IdfObject::comment ( ) const

Returns the comment block associated with the object.

boost::optional<std::string> openstudio::IdfObject::createName ( bool  overwrite = true)

Sets the name field to a new, unique name, if the name field exists and (is empty or overwrite == true).

Returns false otherwise. Created name is returned.

std::vector<unsigned> openstudio::IdfObject::dataFields ( ) const

Returns the indices of all fields that are not managedObjectListFields().

bool openstudio::IdfObject::dataFieldsEqual ( const IdfObject other) const

Checks for equality of data (non-managedObjectList) fields.

Prerequisite: iddObject()s must be equal. For objects with handle fields, checks for equality of handle OR equality of name.

std::vector<std::string> openstudio::IdfObject::eraseExtensibleGroup ( unsigned  groupIndex)

Erases the extensible group at groupIndex, if possible.

Returns the erased data, and preserves the relative order of the remaining data if successful. Otherwise, the returned vector will be empty.

std::vector<IdfExtensibleGroup> openstudio::IdfObject::extensibleGroups ( ) const

Returns this object's IdfExtensibleGroups.

boost::optional<std::string> openstudio::IdfObject::fieldComment ( unsigned  index,
bool  returnDefault = false 
) const

Returns the comment associated with field index, if one exists.

Optionally, if returnDefault is passed in as true, and no field comment exists for index, fieldComment will return a comment-ized version of the IddField name, following a commonly used Idf convention.

boost::optional<double> openstudio::IdfObject::getDouble ( unsigned  index,
bool  returnDefault = false 
) const

Get the value of the field at index, converted to double, if possible.

Returns an uninitialized object if the conversion is unsuccessful for any reason. Logs a warning if the conversion fails, the field is RealType, and the field is not equal to 'autocalculate', 'autosize', or the empty string.

Optionally, if returnDefault is passed in as true, getDouble will return the default value for non-existent (non-extensible) fields and fields with empty data, if a real-valued default exists.

IdfExtensibleGroup openstudio::IdfObject::getExtensibleGroup ( unsigned  groupIndex) const

Returns the IdfExtensibleGroup at groupIndex, if it exists.

Otherwise, return value will be .empty().

boost::optional<int> openstudio::IdfObject::getInt ( unsigned  index,
bool  returnDefault = false 
) const

Get value of the field at index, converted to int, if possible.

Returns an uninitialized object if the conversion is unsuccessful for any reason. Logs a warning if the conversion fails, the field is IntegerType, and the field is not equal to 'autocalculate', 'autosize', or the empty string.

Optionally, if returnDefault is passed in as true, getInt will return the default value for non-existent (non-extensible) fields and fields with empty data, if an int default exists.

OSOptionalQuantity openstudio::IdfObject::getQuantity ( unsigned  index,
bool  returnDefault = false,
bool  returnIP = false 
) const

Returns the Quantity at index, if possible.

Uses markup in IDD to determine the units. If returnIP == true, uses the IP unit mark-up in the IDD to perform a conversion.

boost::optional<std::string> openstudio::IdfObject::getString ( unsigned  index,
bool  returnDefault = false,
bool  returnUninitializedEmpty = false 
) const

Get the value of field index, if index < numFields().

Optionally, if returnDefault is passed in as true, getString will return the default value for non-existent (non-extensible) fields and fields with empty data, if a default exists. If the default does not exist or is not requested and the field is empty then returnUninitializedEmpty is used to determine if an uninitialized result is returned.

boost::optional<unsigned> openstudio::IdfObject::getUnsigned ( unsigned  index,
bool  returnDefault = false 
) const

Get the value of the field at index, converted to unsigned, if possible.

Returns an uninitialized object if the conversion is unsuccessful for any reason. Logs a warning if the conversion fails, the field is IntegerType, there is a minBound >= 0, and the field is not equal to 'autocalculate', 'autosize', or the empty string.

Optionally, if returnDefault is passed in as true, getUnsigned will return the default value for non-existent (non-extensible) fields and fields with empty data, if an unsigned default exists.

boost::optional<QUrl> openstudio::IdfObject::getURL ( unsigned  index,
bool  returnDefault = false 
) const

Get value of the field at index, converted to qurl, if possible.

Returns an uninitialized object if the conversion is unsuccessful for any reason. Logs a warning if the conversion fails, the field is URLType. Optionally, if returnDefault is passed in as true, getURL will return the default value for non-existent (non-extensible) fields and fields with empty data, if a url default exists.

Handle openstudio::IdfObject::handle ( ) const

Returns this object's handle, which is only valid in the containing Workspace.

IddObject openstudio::IdfObject::iddObject ( ) const

Get this object's IddObject.

IdfExtensibleGroup openstudio::IdfObject::insertExtensibleGroup ( unsigned  groupIndex)

Inserts a new extensible group at groupIndex, if possible.

Return value will be empty() if the operation cannot be completed for any reason.

IdfExtensibleGroup openstudio::IdfObject::insertExtensibleGroup ( unsigned  groupIndex,
const std::vector< std::string > &  values 
)

Inserts a new extensible group at groupIndex, if possible.

Return value will be empty() if the operation cannot be completed for any reason.

bool openstudio::IdfObject::isDataField ( unsigned  index) const

Returns true if index is in dataFields().

bool openstudio::IdfObject::isEmpty ( unsigned  index) const

Returns true if the field is empty.

bool openstudio::IdfObject::isObjectListField ( unsigned  index) const

Returns true if index is in objectListFields().

bool openstudio::IdfObject::isValid ( StrictnessLevel  level) const

Returns true if this IdfObject is valid, that is, has no errors at or below level.

static boost::optional<IdfObject> openstudio::IdfObject::load ( const std::string &  text)
static

Constructor from text.

Parses text and queries the IddFactory for its IddObject.

static boost::optional<IdfObject> openstudio::IdfObject::load ( const std::string &  text,
const IddObject iddObject 
)
static

Constructor from text and an explicit iddObject.

boost::optional<unsigned> openstudio::IdfObject::maxExtensibleGroups ( ) const

Returns the maximum number of IdfExtensibleGroups an object of this type must have to be valid.

boost::optional<unsigned> openstudio::IdfObject::maxFields ( ) const

Returns the maximum number of fields an object of this type can have and still be valid.

unsigned openstudio::IdfObject::minExtensibleGroups ( ) const

Returns the minimum number of IdfExtensibleGroups an object of this type must have to be valid.

unsigned openstudio::IdfObject::minFields ( ) const

Returns the minimum number of fields an object of this type must have to be valid.

boost::optional<std::string> openstudio::IdfObject::name ( bool  returnDefault = false) const

Get the name of the object, if it exists.

Optionally, if returnDefault is passed in as true, name will return the default name, if it exists.

unsigned openstudio::IdfObject::numExtensibleGroups ( ) const

Returns the number of extensible groups in the object.

unsigned openstudio::IdfObject::numFields ( ) const

Returns the current number of fields (including extensible groups) in the object.

unsigned openstudio::IdfObject::numNonextensibleFields ( ) const

Returns the current number of non-extensible fields in the object.

std::vector<unsigned> openstudio::IdfObject::objectListFields ( ) const

Returns the indices of all fields that can point to other objects.

WorkspaceObject manages all

\object-list

fields whose reference lists are unambiguously associated with an index-0 name field.

bool openstudio::IdfObject::objectListFieldsEqual ( const IdfObject other) const

Checks for equality of objectListFields().

Prerequisite: iddObject()s must be equal.

bool openstudio::IdfObject::objectListFieldsNonConflicting ( const IdfObject other) const

Returns true if for all managedObjectListFields() that for both objects are non-empty, the values are equal (using the same criteria as objectListFieldsEqual).

Prerequisite: iddObject()s must be equal.

bool openstudio::IdfObject::operator!= ( const IdfObject other) const

Negation of operator==.

bool openstudio::IdfObject::operator== ( const IdfObject other) const

Equality comparator for IdfObjects.

Objects must be exactly equal, that is, they must share data for the operator to return true.

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

cast to optional of type T

std::vector<std::string> openstudio::IdfObject::popExtensibleGroup ( )

Pops the final extensible group from the object, if possible.

Returns the popped data if successful. Otherwise, the returned vector will be empty.

std::ostream& openstudio::IdfObject::print ( std::ostream &  os) const

Serialize this object to os as Idf text.

static int openstudio::IdfObject::printedFieldSpace ( )
static

Returns the width, in characters, of the default amount of space given to field data during printing.

std::ostream& openstudio::IdfObject::printField ( std::ostream &  os,
unsigned  index,
bool  isLastField = false 
) const

Serialize field index in the format used by full object print.

If not isLastField, the field value is followed by a ','. Otherwise, the object is ended by using a ';'.

std::ostream& openstudio::IdfObject::printName ( std::ostream &  os,
bool  hasFields = true 
) const

Serialize just the preceding comments and name of this IdfObject in the format used by full object print.

If hasFields, the name is followed by a ','. Otherwise, the name is followed by a ';'.

IdfExtensibleGroup openstudio::IdfObject::pushExtensibleGroup ( )

Pushes a new extensible group onto the object, if possible.

Return value will be empty() if the operation cannot be completed for any reason.

IdfExtensibleGroup openstudio::IdfObject::pushExtensibleGroup ( const std::vector< std::string > &  values)

Pushes a new extensible group onto the object, if possible.

Return value will be empty() if the operation cannot be completed for any reason.

std::vector<unsigned> openstudio::IdfObject::requiredFields ( ) const

Returns the indices of all fields that are required, as defined by the IddObject.

void openstudio::IdfObject::setComment ( const std::string &  msg)

Sets the comment block associated with the object.

Will prepend comment characters as necessary.

bool openstudio::IdfObject::setDouble ( unsigned  index,
double  value 
)

Sets the field at index to value, if possible.

Returns false if the value cannot be set for any reason. (Perhaps index >= numFields().)

bool openstudio::IdfObject::setFieldComment ( unsigned  index,
const std::string &  cmnt 
)

Sets the comment associated with field index, if that field exists.

Otherwise returns false.

bool openstudio::IdfObject::setInt ( unsigned  index,
int  value 
)

Sets the field at index to value, if possible.

Returns false if the value cannot be set for any reason. (Perhaps index >= numFields(), the field is not IntegerType, or the value is out of bounds per IddField.properties()).

boost::optional<std::string> openstudio::IdfObject::setName ( const std::string &  newName)

Sets the name field if it exists, returning the actual name string set.

Returns false otherwise. The return value and newName may differ (by an appended integer) if a conflict with newName was detected. Name conflicts will not be automatically avoided in IDF (text-only) mode.

bool openstudio::IdfObject::setQuantity ( unsigned  index,
const Quantity q 
)

Sets the field at index to q, if possible.

Returns false if the units of q cannot be converted to getUnits(index).

bool openstudio::IdfObject::setString ( unsigned  index,
const std::string &  value 
)

Sets the field at index to value, if possible.

Returns false if the value cannot be set for any reason. (Perhaps index >= numFields().)

bool openstudio::IdfObject::setUnsigned ( unsigned  index,
unsigned  value 
)

Sets the field at index to value, if possible.

Returns false if the value cannot be set for any reason. (Perhaps index >= numFields(), the field is not IntegerType, or the value is out of bounds per IddField.properties()).

ValidityReport openstudio::IdfObject::validityReport ( StrictnessLevel  level,
bool  checkNames = true 
) const

Returns a ValidityReport for this IdfObject containing all errors at or below level.

Friends And Related Function Documentation

template<typename T , typename U >
std::vector< T > castVector ( const std::vector< U > &  objects)
related

Helper function to cast a whole vector of objects.

template<typename T >
std::vector< Handle > getHandles ( const std::vector< T > &  objects)
related

Helper function to get the handles of a vector of objects.

typedef std::pair<IdfObject,IdfObject> IdfObjectPair
related
typedef std::vector<IdfObject> IdfObjectVector
related
std::ostream & operator<< ( std::ostream &  os,
const IdfObject IdfObject 
)
related
typedef boost::optional<IdfObject> OptionalIdfObject
related
template<typename T , typename U >
std::vector< T > subsetCastVector ( const std::vector< U > &  original)
related

Returns a subset of original cast to a new type, only keeping those objects for which the optionalCast is successful.