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

#include "IdfObject.hpp"

Inheritance diagram for openstudio::IdfObject:

Public Member Functions

 IdfObject (IddObjectType type, bool fastName=false)
 IdfObject (const IddObject &, bool fastName=false)
 IdfObject (const IdfObject &other)
virtual ~IdfObject ()
IdfObject clone (bool keepHandle=false) const
Handle handle () const
IddObject iddObject () const
std::string comment () const
boost::optional< std::string > fieldComment (unsigned index, bool returnDefault=false) const
boost::optional< std::string > name (bool returnDefault=false) const
std::string nameString (bool returnDefault=false) const
std::string briefDescription () const
bool isEmpty (unsigned index) const
boost::optional< std::string > getString (unsigned index, bool returnDefault=false, bool returnUninitializedEmpty=false) const
boost::optional< double > getDouble (unsigned index, bool returnDefault=false) const
OSOptionalQuantity getQuantity (unsigned index, bool returnDefault=false, bool returnIP=false) const
boost::optional< unsigned > getUnsigned (unsigned index, bool returnDefault=false) const
boost::optional< intgetInt (unsigned index, bool returnDefault=false) const
boost::optional< QUrl > getURL (unsigned index, bool returnDefault=false) const
IdfExtensibleGroup getExtensibleGroup (unsigned groupIndex) const
std::vector< IdfExtensibleGroupextensibleGroups () const
void setComment (const std::string &msg)
bool setFieldComment (unsigned index, const std::string &cmnt)
boost::optional< std::string > setName (const std::string &newName)
boost::optional< std::string > createName (bool overwrite=true)
bool setString (unsigned index, const std::string &value)
bool setDouble (unsigned index, double value)
bool setQuantity (unsigned index, const Quantity &q)
bool setUnsigned (unsigned index, unsigned value)
bool setInt (unsigned index, int value)
IdfExtensibleGroup pushExtensibleGroup ()
IdfExtensibleGroup pushExtensibleGroup (const std::vector< std::string > &values)
IdfExtensibleGroup insertExtensibleGroup (unsigned groupIndex)
IdfExtensibleGroup insertExtensibleGroup (unsigned groupIndex, const std::vector< std::string > &values)
std::vector< std::string > popExtensibleGroup ()
std::vector< std::string > eraseExtensibleGroup (unsigned groupIndex)
std::vector< std::vector
< std::string > > 
clearExtensibleGroups ()
unsigned numFields () const
unsigned numNonextensibleFields () const
unsigned minFields () const
boost::optional< unsigned > maxFields () const
unsigned numExtensibleGroups () const
unsigned minExtensibleGroups () const
boost::optional< unsigned > maxExtensibleGroups () const
bool isObjectListField (unsigned index) const
std::vector< unsigned > objectListFields () const
bool isDataField (unsigned index) const
std::vector< unsigned > dataFields () const
std::vector< unsigned > requiredFields () const
bool isValid (StrictnessLevel level) const
ValidityReport validityReport (StrictnessLevel level, bool checkNames=true) const
bool dataFieldsEqual (const IdfObject &other) const
bool objectListFieldsEqual (const IdfObject &other) const
bool objectListFieldsNonConflicting (const IdfObject &other) const
bool operator== (const IdfObject &other) const
bool operator!= (const IdfObject &other) const
template<typename T >
cast () const
template<typename T >
boost::optional< T > optionalCast () const

Protected Types

typedef detail::IdfObject_Impl ImplType

Protected Member Functions

 IdfObject (std::shared_ptr< detail::IdfObject_Impl > impl)

Related Functions

template<typename T , typename U >
std::vector< T > castVector (const std::vector< U > &objects)
template<typename T >
std::vector< Handle > getHandles (const std::vector< T > &objects)
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)

Serialization

std::ostream & print (std::ostream &os) const
std::ostream & printName (std::ostream &os, bool hasFields=true) const
std::ostream & printField (std::ostream &os, unsigned index, bool isLastField=false) const
static boost::optional< IdfObjectload (const std::string &text)
static boost::optional< IdfObjectload (const std::string &text, const IddObject &iddObject)
static int printedFieldSpace ()

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.

std::string openstudio::IdfObject::nameString ( bool  returnDefault = false) const

Returns the name if set or returns an empty string.

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.