OpenStudio:measure
 All Classes Namespaces Functions Typedefs Enumerations Enumerator Pages
Related Functions | List of all members
openstudio::measure::OSArgument Class Reference

#include <OSArgument.hpp>

Public Member Functions

Constructors and Destructors
 OSArgument ()
 
 OSArgument (const std::string &name, const OSArgumentType &type, bool required, bool modelDependent)
 
OSArgument clone () const
 Creates a copy with new UUIDs. More...
 
Getters
std::string name () const
 Returns the name of this argument. More...
 
std::string displayName () const
 Returns the display name of this argument. More...
 
boost::optional< std::string > description () const
 Returns the description of this argument. More...
 
OSArgumentType type () const
 Returns this argument's type. More...
 
boost::optional< std::string > units () const
 Returns the units of this argument. More...
 
bool required () const
 Returns true if this argument is required, that is, if the argument must have a value or default value for the measure to run properly. More...
 
bool modelDependent () const
 Returns true if this argument's properties can changed based on the specific model used in the measure. More...
 
bool hasValue () const
 Returns true if this argument's value has been set. More...
 
bool valueAsBool () const
 Returns this argument's value as a bool. More...
 
double valueAsDouble () const
 Returns this argument's value as a double. More...
 
int valueAsInteger () const
 Returns this argument's value as an int. More...
 
std::string valueAsString () const
 Returns this argument's value as a std::string. More...
 
openstudio::path valueAsPath () const
 Returns this argument's value as an openstudio::path. More...
 
Json::Value valueAsJSON () const
 Returns this argument's value as a Json::Value. More...
 
bool hasDefaultValue () const
 Returns true if this argument's default value has been set. More...
 
bool defaultValueAsBool () const
 Returns this argument's default value as a bool. More...
 
double defaultValueAsDouble () const
 Returns this argument's default value as a double. More...
 
int defaultValueAsInteger () const
 Returns this argument's default value as an int. More...
 
std::string defaultValueAsString () const
 Returns this argument's default value as a std::string. More...
 
openstudio::path defaultValueAsPath () const
 Returns this argument's default value as an openstudio::path. More...
 
Json::Value defaultValueAsJSON () const
 Returns this argument's default value as a Json::Value. More...
 
bool hasDomain () const
 Returns true if this argument has a non-null domain. More...
 
OSDomainType domainType () const
 Returns the OSDomainType, which is defaulted to a particular value for each type(). More...
 
std::vector< bool > domainAsBool () const
 Returns the domain as a vector of bools. More...
 
std::vector< double > domainAsDouble () const
 Returns the domain as a vector of doubles. More...
 
std::vector< int > domainAsInteger () const
 Returns the domain as a vector of ints. More...
 
std::vector< std::string > domainAsString () const
 Returns the domain as a vector of strings. More...
 
std::vector< openstudio::path > domainAsPath () const
 Returns the domain as a vector of paths. More...
 
Json::Value domainAsJSON () const
 Returns this argument's domain as a Json::Value. More...
 
Choice Argument Getters
std::vector< std::string > choiceValues () const
 If this is an argument of type() OSArgument::Choice, returns the allowable values. More...
 
std::vector< std::string > choiceValueDisplayNames () const
 Returns a vector the same length as choiceValues() that can be used to display choices to a user. More...
 
std::string valueDisplayName () const
 Returns the display name or actual value for arguments of type() OSArgument::Choice, if a value is set. More...
 
std::string defaultValueDisplayName () const
 Returns the display name or actual default value for arguments of type() OSArgument::Choice, if a default value is set. More...
 
Path Argument Getters
bool isRead () const
 Returns true if type() == OSArgumentType::Path and if the path is to a file that is to be read. More...
 
std::string extension () const
 If type() == OSArgumentType::Path, returns the expected file extension of the path. More...
 
Setters
void setDisplayName (const std::string &displayName)
 Set the display name of this argument. More...
 
void setDescription (const std::string &description)
 Set the description of this argument. More...
 
void setUnits (const std::string &units)
 Set the units for this argument. More...
 
bool setValue (bool value)
 Set the value of this argument by passing in data of a particular type. More...
 
bool setValue (double value)
 
bool setValue (int value)
 
bool setValue (const char *value)
 
bool setValue (const std::string &value)
 
bool setValue (const openstudio::path &value)
 
void clearValue ()
 
bool setDefaultValue (bool defaultValue)
 Set the default value of this argument by passing in data of a particular type. More...
 
bool setDefaultValue (double defaultValue)
 
bool setDefaultValue (int defaultValue)
 
bool setDefaultValue (const char *defaultValue)
 
bool setDefaultValue (const std::string &defaultValue)
 
bool setDefaultValue (const openstudio::path &defaultValue)
 
bool setDomainType (const OSDomainType &domainType)
 Sets the domainType and returns true if domainType is consistent with type, otherwise returns false. More...
 
bool setDomain (const std::vector< bool > &domain)
 Sets the domain of this argument by passing in data of a particular type. More...
 
bool setDomain (const std::vector< double > &domain)
 
bool setDomain (const std::vector< int > &domain)
 
bool setDomain (const std::vector< std::string > &domain)
 
bool setDomain (const std::vector< openstudio::path > &domain)
 
void clearDomain ()
 
bool setMinValue (double minValue)
 Sets the domain type to OSDomainType::Interval and sets minimum value. More...
 
bool setMinValue (int minValue)
 
bool setMaxValue (double maxValue)
 Sets the domain type to OSDomainType::Interval and sets maximum value. More...
 
bool setMaxValue (int maxValue)
 
Serialization
std::string print () const
 Prints argument data for debugging purposes. More...
 
std::string printValue (bool printDefault=true) const
 Returns this argument's value printed to string. More...
 
std::string printDefaultValue () const
 Returns this argument's default value printed to string, if possible. More...
 
Json::Value toJSON () const
 
std::string toJSONString () const
 

Static Public Member Functions

Factory methods
static OSArgument makeBoolArgument (const std::string &name, bool required=true, bool modelDependent=false)
 Creates an OSArgument for bool values. More...
 
static OSArgument makeDoubleArgument (const std::string &name, bool required=true, bool modelDependent=false)
 Creates an OSArgument for double values. More...
 
static OSArgument makeIntegerArgument (const std::string &name, bool required=true, bool modelDependent=false)
 Creates an OSArgument for int values. More...
 
static OSArgument makeStringArgument (const std::string &name, bool required=true, bool modelDependent=false)
 Creates an OSArgument for string values. More...
 
static OSArgument makeChoiceArgument (const std::string &name, const std::vector< std::string > &choices, bool required=true, bool modelDependent=false)
 Creates an OSArgument for choice values. More...
 
static OSArgument makeChoiceArgument (const std::string &name, const std::vector< std::string > &choices, const std::vector< std::string > &displayNames, bool required=true, bool modelDependent=false)
 Creates an OSArgument for choice values. More...
 
static OSArgument makeChoiceArgument (const std::string &name, const std::map< std::string, std::string > &choices_to_display_values_map, bool required=true, bool modelDependent=false)
 
static OSArgument makePathArgument (const std::string &name, bool isRead, const std::string &extension, bool required=true, bool modelDependent=false)
 Creates an OSArgument for path values. More...
 
static OSArgument makeSeparatorArgument (const std::string &name, bool modelDependent=false)
 Creates a separator OSArgument, cannot be used to store a value, cannot be required. More...
 

Related Functions

(Note that these are not member functions.)

std::map< std::string, OSArgumentconvertOSArgumentVectorToMap (const std::vector< OSArgument > &arguments)
 Converts a vector of OSArgument to a map of OSArgument using name as the key. More...
 
OSArgument makeChoiceArgumentOfWorkspaceObjects (const std::string &name, const IddObjectType &iddObjectType, const Workspace &workspace, bool required=true)
 Creates a choice argument with object handles as its values and object names as its display names by querying workspace for all of its objects of type iddObjectType. More...
 
OSArgument makeChoiceArgumentOfWorkspaceObjects (const std::string &name, const std::string &referenceName, const Workspace &workspace, bool required=true)
 Creates a choice argument with object handles as its values and object names as its display names by querying workspace for all of its objects with reference referenceName. More...
 
std::ostream & operator<< (std::ostream &os, const OSArgument &arg)
 Prints argument data to ostream for debugging purposes. More...
 
using OptionalOSArgument = boost::optional< OSArgument >
 
using OSArgumentMap = std::map< std::string, OSArgument >
 
using OSArgumentVector = std::vector< OSArgument >
 
using UserScriptInfo = std::pair< openstudio::path, std::vector< OSArgument >>
 

Detailed Description

OSArgument is an argument to an OSMeasure.

Constructor & Destructor Documentation

openstudio::measure::OSArgument::OSArgument ( )
openstudio::measure::OSArgument::OSArgument ( const std::string &  name,
const OSArgumentType type,
bool  required,
bool  modelDependent 
)

Member Function Documentation

std::vector<std::string> openstudio::measure::OSArgument::choiceValueDisplayNames ( ) const

Returns a vector the same length as choiceValues() that can be used to display choices to a user.

Each element is the explicit choice display name, if that exists, or the actual choice value, otherwise.

std::vector<std::string> openstudio::measure::OSArgument::choiceValues ( ) const

If this is an argument of type() OSArgument::Choice, returns the allowable values.

Otherwise the returned vector will be .empty().

void openstudio::measure::OSArgument::clearDomain ( )
void openstudio::measure::OSArgument::clearValue ( )
OSArgument openstudio::measure::OSArgument::clone ( ) const

Creates a copy with new UUIDs.

bool openstudio::measure::OSArgument::defaultValueAsBool ( ) const

Returns this argument's default value as a bool.

Throws if not hasDefaultValue() or if type() != OSArgumentType::Boolean.

double openstudio::measure::OSArgument::defaultValueAsDouble ( ) const

Returns this argument's default value as a double.

Throws if not hasDefaultValue() or if type() != OSArgumentType::Double.

int openstudio::measure::OSArgument::defaultValueAsInteger ( ) const

Returns this argument's default value as an int.

Throws if not hasDefaultValue() or if type() != OSArgumentType::Integer.

Json::Value openstudio::measure::OSArgument::defaultValueAsJSON ( ) const

Returns this argument's default value as a Json::Value.

Will convert nicely to ruby/python native types. Returns nullValue if it doesn't have one

openstudio::path openstudio::measure::OSArgument::defaultValueAsPath ( ) const

Returns this argument's default value as an openstudio::path.

Throws if not hasDefaultValue() or if type() != OSArgumentType::Path.

std::string openstudio::measure::OSArgument::defaultValueAsString ( ) const

Returns this argument's default value as a std::string.

If type() != OSArgumentType::String, prints this argument's default value to produce the result. Throws if not hasDefaultValue().

std::string openstudio::measure::OSArgument::defaultValueDisplayName ( ) const

Returns the display name or actual default value for arguments of type() OSArgument::Choice, if a default value is set.

Otherwise throws.

boost::optional<std::string> openstudio::measure::OSArgument::description ( ) const

Returns the description of this argument.

std::string openstudio::measure::OSArgument::displayName ( ) const

Returns the display name of this argument.

std::vector<bool> openstudio::measure::OSArgument::domainAsBool ( ) const

Returns the domain as a vector of bools.

Will throw if not hasDomain() or type() != OSArgumentType::Boolean.

std::vector<double> openstudio::measure::OSArgument::domainAsDouble ( ) const

Returns the domain as a vector of doubles.

Will throw if not hasDomain() or type() != OSArgumentType::Double.

std::vector<int> openstudio::measure::OSArgument::domainAsInteger ( ) const

Returns the domain as a vector of ints.

Will throw if not hasDomain() or type() != OSArgumentType::Integer.

Json::Value openstudio::measure::OSArgument::domainAsJSON ( ) const

Returns this argument's domain as a Json::Value.

Will convert nicely to ruby/python native types. Returns nullValue if it doesn't have one, Json::arrayValue otherwise

std::vector<openstudio::path> openstudio::measure::OSArgument::domainAsPath ( ) const

Returns the domain as a vector of paths.

Will throw if not hasDomain() or type() != OSArgumentType::Path.

std::vector<std::string> openstudio::measure::OSArgument::domainAsString ( ) const

Returns the domain as a vector of strings.

Will throw if not hasDomain().

OSDomainType openstudio::measure::OSArgument::domainType ( ) const

Returns the OSDomainType, which is defaulted to a particular value for each type().

If domainType == OSDomainType::Interval then the domain getters will return two elements. The first will be the minimum value, and the second will be the maximum. If domainType == OSDomainType::Enumeration, then all of the possible/acceptable values will be explicitly listed.

std::string openstudio::measure::OSArgument::extension ( ) const

If type() == OSArgumentType::Path, returns the expected file extension of the path.

Otherwise, the return value is .empty().

bool openstudio::measure::OSArgument::hasDefaultValue ( ) const

Returns true if this argument's default value has been set.

bool openstudio::measure::OSArgument::hasDomain ( ) const

Returns true if this argument has a non-null domain.

bool openstudio::measure::OSArgument::hasValue ( ) const

Returns true if this argument's value has been set.

bool openstudio::measure::OSArgument::isRead ( ) const

Returns true if type() == OSArgumentType::Path and if the path is to a file that is to be read.

static OSArgument openstudio::measure::OSArgument::makeBoolArgument ( const std::string &  name,
bool  required = true,
bool  modelDependent = false 
)
static

Creates an OSArgument for bool values.

Defaults domainType() to OSDomainType::Enumeration.

static OSArgument openstudio::measure::OSArgument::makeChoiceArgument ( const std::string &  name,
const std::vector< std::string > &  choices,
bool  required = true,
bool  modelDependent = false 
)
static

Creates an OSArgument for choice values.

Defaults domainType() to OSDomainType::Enumeration.

static OSArgument openstudio::measure::OSArgument::makeChoiceArgument ( const std::string &  name,
const std::vector< std::string > &  choices,
const std::vector< std::string > &  displayNames,
bool  required = true,
bool  modelDependent = false 
)
static

Creates an OSArgument for choice values.

Defaults domainType() to OSDomainType::Enumeration.

static OSArgument openstudio::measure::OSArgument::makeChoiceArgument ( const std::string &  name,
const std::map< std::string, std::string > &  choices_to_display_values_map,
bool  required = true,
bool  modelDependent = false 
)
static
static OSArgument openstudio::measure::OSArgument::makeDoubleArgument ( const std::string &  name,
bool  required = true,
bool  modelDependent = false 
)
static

Creates an OSArgument for double values.

Defaults domaintType() to OSDomainType::Interval.

static OSArgument openstudio::measure::OSArgument::makeIntegerArgument ( const std::string &  name,
bool  required = true,
bool  modelDependent = false 
)
static

Creates an OSArgument for int values.

Defaults domaintType() to OSDomainType::Interval.

static OSArgument openstudio::measure::OSArgument::makePathArgument ( const std::string &  name,
bool  isRead,
const std::string &  extension,
bool  required = true,
bool  modelDependent = false 
)
static

Creates an OSArgument for path values.

Defaults domainType() to OSDomainType::Enumeration.

static OSArgument openstudio::measure::OSArgument::makeSeparatorArgument ( const std::string &  name,
bool  modelDependent = false 
)
static

Creates a separator OSArgument, cannot be used to store a value, cannot be required.

static OSArgument openstudio::measure::OSArgument::makeStringArgument ( const std::string &  name,
bool  required = true,
bool  modelDependent = false 
)
static

Creates an OSArgument for string values.

Defaults domainType() to OSDomainType::Enumeration.

bool openstudio::measure::OSArgument::modelDependent ( ) const

Returns true if this argument's properties can changed based on the specific model used in the measure.

A choice argument which lists objects in the model would be model dependent.

std::string openstudio::measure::OSArgument::name ( ) const

Returns the name of this argument.

std::string openstudio::measure::OSArgument::print ( ) const

Prints argument data for debugging purposes.

std::string openstudio::measure::OSArgument::printDefaultValue ( ) const

Returns this argument's default value printed to string, if possible.

If there is no default value, the string will be .empty().

std::string openstudio::measure::OSArgument::printValue ( bool  printDefault = true) const

Returns this argument's value printed to string.

If printDefault, returns the default value if in the case of !hasValue() && hasDefaultValue(). If there is no value to print, the returned string will be .empty().

bool openstudio::measure::OSArgument::required ( ) const

Returns true if this argument is required, that is, if the argument must have a value or default value for the measure to run properly.

bool openstudio::measure::OSArgument::setDefaultValue ( bool  defaultValue)

Set the default value of this argument by passing in data of a particular type.

The method will do nothing and return false if the data is of an incorrect type. These methods do not check defaultValue against the domain (if set), as the domain is just a guideline for users. The string setter will try to convert the string to the correct type for this argument. Integers can be used to set the default values of arguments of type double. A double that is really an int (eg: 1.0) can also be accepted to set integer arguments.

bool openstudio::measure::OSArgument::setDefaultValue ( double  defaultValue)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setDefaultValue ( int  defaultValue)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setDefaultValue ( const char *  defaultValue)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setDefaultValue ( const std::string &  defaultValue)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setDefaultValue ( const openstudio::path &  defaultValue)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void openstudio::measure::OSArgument::setDescription ( const std::string &  description)

Set the description of this argument.

void openstudio::measure::OSArgument::setDisplayName ( const std::string &  displayName)

Set the display name of this argument.

bool openstudio::measure::OSArgument::setDomain ( const std::vector< bool > &  domain)

Sets the domain of this argument by passing in data of a particular type.

The method will do nothing and return false if the data is of an incorrect type or size. A vector of size 2 is expected for OSDomainType::Interval.

bool openstudio::measure::OSArgument::setDomain ( const std::vector< double > &  domain)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setDomain ( const std::vector< int > &  domain)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setDomain ( const std::vector< std::string > &  domain)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setDomain ( const std::vector< openstudio::path > &  domain)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setDomainType ( const OSDomainType domainType)

Sets the domainType and returns true if domainType is consistent with type, otherwise returns false.

If the domainType changes, the domain will be cleared before returning.

bool openstudio::measure::OSArgument::setMaxValue ( double  maxValue)

Sets the domain type to OSDomainType::Interval and sets maximum value.

Preserves existing minimum value or sets it to infinity if it does not exist.

bool openstudio::measure::OSArgument::setMaxValue ( int  maxValue)
bool openstudio::measure::OSArgument::setMinValue ( double  minValue)

Sets the domain type to OSDomainType::Interval and sets minimum value.

Preserves existing maximum value or sets it to infinity if it does not exist. Does not check for compatibility with current value, default value, or that min < max.

bool openstudio::measure::OSArgument::setMinValue ( int  minValue)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void openstudio::measure::OSArgument::setUnits ( const std::string &  units)

Set the units for this argument.

bool openstudio::measure::OSArgument::setValue ( bool  value)

Set the value of this argument by passing in data of a particular type.

The method will do nothing and return false if the data is of an incorrect type. These methods do not check value against the domain (if set), as the domain is just a guideline for users. The string setter will try to convert the string to the correct type for this argument. Integers can be used to set the values of arguments of type double. A double that is really an int (eg: 1.0) can also be accepted to set integer arguments.

bool openstudio::measure::OSArgument::setValue ( double  value)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setValue ( int  value)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setValue ( const char *  value)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setValue ( const std::string &  value)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool openstudio::measure::OSArgument::setValue ( const openstudio::path &  value)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Json::Value openstudio::measure::OSArgument::toJSON ( ) const
std::string openstudio::measure::OSArgument::toJSONString ( ) const
OSArgumentType openstudio::measure::OSArgument::type ( ) const

Returns this argument's type.

boost::optional<std::string> openstudio::measure::OSArgument::units ( ) const

Returns the units of this argument.

bool openstudio::measure::OSArgument::valueAsBool ( ) const

Returns this argument's value as a bool.

Throws if not hasValue() or if type() != OSArgumentType::Boolean.

double openstudio::measure::OSArgument::valueAsDouble ( ) const

Returns this argument's value as a double.

Throws if not hasValue() or if type() != OSArgumentType::Double.

int openstudio::measure::OSArgument::valueAsInteger ( ) const

Returns this argument's value as an int.

Throws if not hasValue() or if type() != OSArgumentType::Integer.

Json::Value openstudio::measure::OSArgument::valueAsJSON ( ) const

Returns this argument's value as a Json::Value.

Will convert nicely to ruby/python native types. Returns nullValue if it doesn't have one

openstudio::path openstudio::measure::OSArgument::valueAsPath ( ) const

Returns this argument's value as an openstudio::path.

Throws if not hasValue() or if type() != OSArgumentType::Path.

std::string openstudio::measure::OSArgument::valueAsString ( ) const

Returns this argument's value as a std::string.

If type() != OSArgumentType::String, prints this argument's value to produce the result. Throws if not hasValue().

std::string openstudio::measure::OSArgument::valueDisplayName ( ) const

Returns the display name or actual value for arguments of type() OSArgument::Choice, if a value is set.

Otherwise throws.

Friends And Related Function Documentation

std::map< std::string, OSArgument > convertOSArgumentVectorToMap ( const std::vector< OSArgument > &  arguments)
related

Converts a vector of OSArgument to a map of OSArgument using name as the key.

OSArgument makeChoiceArgumentOfWorkspaceObjects ( const std::string &  name,
const IddObjectType &  iddObjectType,
const Workspace &  workspace,
bool  required = true 
)
related

Creates a choice argument with object handles as its values and object names as its display names by querying workspace for all of its objects of type iddObjectType.

The resulting argument does not attempt to preserve workspace, so the handles and names will only be valid if the workspace to which the argument is applied is the same or closely related to workspace.

OSArgument makeChoiceArgumentOfWorkspaceObjects ( const std::string &  name,
const std::string &  referenceName,
const Workspace &  workspace,
bool  required = true 
)
related

Creates a choice argument with object handles as its values and object names as its display names by querying workspace for all of its objects with reference referenceName.

The resulting argument does not attempt to preserve workspace, so the handles and names will only be valid if the workspace to which the argument is applied is the same or closely related to workspace.

std::ostream & operator<< ( std::ostream &  os,
const OSArgument arg 
)
related

Prints argument data to ostream for debugging purposes.

using OptionalOSArgument = boost::optional<OSArgument>
related
using OSArgumentMap = std::map<std::string, OSArgument>
related
using OSArgumentVector = std::vector<OSArgument>
related
using UserScriptInfo = std::pair<openstudio::path, std::vector<OSArgument>>
related