SST  12.0.0
StructuralSimulationToolkit
SST::Params Class Reference

Parameter store. More...

#include <params.h>

Inheritance diagram for SST::Params:
SST::Core::Serialization::serializable

Public Types

typedef std::string key_type
 
typedef std::set< key_type,
KeyCompare > 
KeySet_t
 

Public Member Functions

bool enableVerify (bool enable)
 Enable or disable parameter verification on an instance of Params. More...
 
size_t size () const
 Returns the size of the Params. More...
 
bool empty () const
 Returns true if the Params is empty. More...
 
 Params ()
 Create a new, empty Params.
 
 Params (const Params &old)
 Create a copy of a Params object.
 
Paramsoperator= (const Params &old)
 Assignment operator. More...
 
void clear ()
 Erases all elements, including deleting reference to global param sets.
 
size_t count (const key_type &k) const
 Finds the number of elements with given key. More...
 
template<class T >
std::enable_if< not
std::is_same< std::string, T >
::value, T >::type 
find (const std::string &k, T default_value, bool &found) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
find (const std::string &k, const std::string &default_value, bool &found) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
std::enable_if< std::is_same
< bool, T >::value, T >::type 
find (const std::string &k, const char *default_value, bool &found) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
find (const std::string &k, T default_value) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
find (const std::string &k, const std::string &default_value) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
std::enable_if< std::is_same
< bool, T >::value, T >::type 
find (const std::string &k, const char *default_value) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
find (const std::string &k) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
std::enable_if< not
std::is_same< bool, T >::value,
T >::type 
find (const std::string &k, bool &found) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
void find_array (const key_type &k, std::vector< T > &vec) const
 Find a Parameter value in the set, and return its value as a vector of T's. More...
 
template<class T >
void find_set (const key_type &k, std::set< T > &set) const
 Find a Parameter value in the set, and return its value as a set of T's. More...
 
template<class keyT , class valT >
void find_map (const key_type &k, std::map< keyT, valT > &map) const
 Find a Parameter value in the set, and return its value as a map<keyT,valT>. More...
 
bool is_value_array (const key_type &k) const
 Checks to see if the value associated with the given key is considered to be an array. More...
 
void print_all_params (std::ostream &os, const std::string &prefix="") const
 Print all key/value parameter pairs to specified ostream.
 
void print_all_params (Output &out, const std::string &prefix="") const
 Print all key/value parameter pairs to specified ostream.
 
void insert (const std::string &key, const std::string &value, bool overwrite=true)
 Add a key/value pair into the param object. More...
 
void insert (const Params &params)
 Add contents of input Params object to current Params object. More...
 
std::set< std::string > getKeys () const
 Get all the keys contained in the Params object. More...
 
Params get_scoped_params (const std::string &scope) const
 Returns a new parameter object with parameters that match the specified scoped prefix (scopes are separated with "." The keys will be stripped of the "scope." prefix. More...
 
bool contains (const key_type &k) const
 Search the container for a particular key. More...
 
void pushAllowedKeys (const KeySet_t &keys)
 
void popAllowedKeys ()
 Removes the most recent set of keys considered allowed.
 
void serialize_order (SST::Core::Serialization::serializer &ser) override
 
- Public Member Functions inherited from SST::Core::Serialization::serializable
virtual const char * cls_name () const =0
 
virtual uint32_t cls_id () const =0
 
virtual std::string serialization_name () const =0
 

Static Public Member Functions

static void enableVerify ()
 Enable, on a global scale, parameter verification. More...
 

Friends

class SST::ConfigGraph
 
class SST::ConfigComponent
 
class SST::Core::ConfigGraphOutput
 
class SST::SSTModelDescription
 

Additional Inherited Members

- Static Public Attributes inherited from SST::Core::Serialization::serializable
static constexpr uint32_t NullClsId = std::numeric_limits<uint32_t>::max()
 
- Protected Types inherited from SST::Core::Serialization::serializable
enum  cxn_flag_t { ConstructorFlag }
 
- Static Protected Member Functions inherited from SST::Core::Serialization::serializable
static void serializable_abort (uint32_t line, const char *file, const char *func, const char *obj)
 

Detailed Description

Parameter store.

Stores key-value pairs as std::strings and provides a templated find method for finding values and converting them to arbitrary types (

See Also
find()).

NOTE: Params objects should only be used for simulation initialization, a Params object should not be used as part of an event, as serialization of Params objects only works correctly as part of ConfigGraph serialization.

Member Typedef Documentation

typedef std::string SST::Params::key_type

Type of key (string)

typedef std::set<key_type, KeyCompare> SST::Params::KeySet_t

Type of a set of keys

Member Function Documentation

bool SST::Params::contains ( const key_type k) const

Search the container for a particular key.

This will search both local and global params.

Parameters
kKey to search for
Returns
True if the params contains the key, false otherwise
size_t SST::Params::count ( const key_type k) const

Finds the number of elements with given key.

The call will check both local and global params, but will still only report one instance if the given key is found in both the local and global param sets.

Parameters
kKey of (key, value) pairs to be located.
Returns
Number of elements with specified key (either 1 or 0).
bool SST::Params::empty ( ) const

Returns true if the Params is empty.

Checks both local and global param sets.

Returns
true if this Params object is empty, false otherwise

References getKeys().

bool SST::Params::enableVerify ( bool  enable)
inline

Enable or disable parameter verification on an instance of Params.

Useful when generating a new set of Params to pass off to a module.

Returns
returns the previous state of the flag

Referenced by get_scoped_params().

static void SST::Params::enableVerify ( )
inlinestatic

Enable, on a global scale, parameter verification.

Used after construction of the config graph so that warnings are not generated during construction.

template<class T >
std::enable_if<not std::is_same<std::string, T>::value, T>::type SST::Params::find ( const std::string &  k,
default_value,
bool &  found 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found
found- set to true if the the parameter was found
Exceptions
std::invalid_argumentIf value in (key, value) can't be converted to type T, an invalid_argument exception is thrown.

Referenced by SST::Statistics::StatisticOutputTextBase::checkOutputParameters(), SST::Statistics::StatisticOutputJSON::checkOutputParameters(), SST::Statistics::StatisticOutputCSV::checkOutputParameters(), and SST::Statistics::StatisticBase::StatisticBase().

template<class T >
T SST::Params::find ( const std::string &  k,
const std::string &  default_value,
bool &  found 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found, specified as a string
found- set to true if the the parameter was found
template<class T >
std::enable_if<std::is_same<bool, T>::value, T>::type SST::Params::find ( const std::string &  k,
const char *  default_value,
bool &  found 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

This version of find is only enabled for bool. This is required because a string literal will be preferentially cast to a bool rather than a string. This ensures that find<bool> works correctly for string literals. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found, specified as a string literal
template<class T >
T SST::Params::find ( const std::string &  k,
default_value 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool), a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found
template<class T >
T SST::Params::find ( const std::string &  k,
const std::string &  default_value 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found, specified as a string
template<class T >
std::enable_if<std::is_same<bool, T>::value, T>::type SST::Params::find ( const std::string &  k,
const char *  default_value 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

This version of find is only enabled for bool. This is required because a string literal will be preferentially cast to a bool rather than a string. This ensures that find<bool> works correctly for string literals.This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found, specified as a string literal
template<class T >
T SST::Params::find ( const std::string &  k) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
template<class T >
std::enable_if<not std::is_same<bool, T>::value, T>::type SST::Params::find ( const std::string &  k,
bool &  found 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type , a std::string, or a class that has a constructor with a std::string as its only parameter. This version of find is not enabled for bool as it conflicts with find<bool>(string key, bool default_value). This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
found- set to true if the the parameter was found
template<class T >
void SST::Params::find_array ( const key_type k,
std::vector< T > &  vec 
) const
inline

Find a Parameter value in the set, and return its value as a vector of T's.

The array will be appended to the end of the vector.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion. The values in the array must be enclosed in square brackets ( [] ), and be comma separated (commas in double or single quotes will not be considered a delimiter). If there are no square brackets, the entire string will be considered one value and a single item will be added to the vector.

More details about parsing the values out of the string:

Parses a string representing an array of tokens. It is tailored to the types strings you get when passing a python list as the param string. When you call addParam() on a python list in the input file, it will call the str() function on the list, which creates a string with the following format: [item1, item2, item3]

The format of the items depends on where they came from. The string for the items are generated by calling the repr() function on them. For strings, this means they will typically be enclosed in single quotes. It is possible that they end up enclosed in double quotes if the string itself contains a single quote. For strings which contain both single and double quotes, the repr() will create a single quoted string with all internal single quotes escaped with '\'. Most other items used in SST do not enclose the string in quotes, though any string that contains a comma would need to be enclosed in quotes, since the comma is the delimiter character used. This is not done automatically, so if you have something that generates a commma in the string created by repr(), you may need to create an array string manually. Also, any string that starts with a quote character, must end with the same quote character.

Tokens are generated by splitting the string on commas that are not within quotes (double or single). All whitespace at the beginning and end of a token is ignored (unless inside quotes). Once the tokens are generated, any quoted string will have the front and back quotes removed. The '\' for any escaped quote of the same type as the front and back is also removed.

Examples:

These will produce the same results: [1, 2, 3, 4, 5] ['1', '2', '3', '4', '5']

Examples of strings using double and/or single quotes: 'This is "a" test' -> This is "a" test "This is 'a' test" -> This is 'a' test 'This "is \'a\'" test' -> This "is 'a'" test 'This "is \"a"" test' -> This "is "a"" test

Parameters
k- Parameter name
vec- vector to append array items to
template<class keyT , class valT >
void SST::Params::find_map ( const key_type k,
std::map< keyT, valT > &  map 
) const
inline

Find a Parameter value in the set, and return its value as a map<keyT,valT>.

The items will be added to the passed in map.

Types keyT and valT must be either a basic numeric type (including bool), a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion. The values in the map must be enclosed in curly braces ( {} ), the key/value pairs must be comma separated (commas in double or single quotes will not be considered a delimiter) and the key and value in the pairs must be separated by a colon (colons in double or single quotes will not be considered a delimiter). If there are no curly braces, the function will throw an std::invalid_argument exception without adding anything to the map.

More details about parsing the values out of the string:

Parses a string representing a set of tokens. It is tailored to the types strings you get when passing a python set as the param string. When you call addParam() on a python set in the input file, it will call the str() function on the set, which creates a string with the following format: {key1 : value1, key2 : value2, key3 : value3}

The format of each item depends on where it came from. The string for the items are generated by calling the repr() function on them. For strings, this means they will typically be enclosed in single quotes. It is possible that they end up enclosed in double quotes if the string itself contains a single quote. For strings which contain both single and double quotes, the repr() will create a single quoted string with all internal single quotes escaped with '\'. Most other items used in SST do not enclose the string in quotes, though any string that contains a comma would need to be enclosed in quotes, since the comma is the delimiter character used. This is not done automatically, so if you have something that generates a commma in the string created by repr(), you may need to create an array string manually. Also, any string that starts with a quote character, must end with the same quote character.

Tokens are generated by splitting the string on commas that are not within quotes (double or single). All whitespace at the beginning and end of a token is ignored (unless inside quotes). Once the tokens are generated, any quoted string will have the front and back quotes removed. The '\' for any escaped quote of the same type as the front and back is also removed.

Examples:

These will produce the same results: {"one" : 1, "two" : 2, "three" : 3, "Four" : 4} {"one" :'1', "two" : '2', "three" : '3', "four" : '4'}

Examples of strings using double and/or single quotes: 'This is "a" test' -> This is "a" test "This is 'a' test" -> This is 'a' test 'This "is \'a\'" test' -> This "is 'a'" test 'This "is \"a"" test' -> This "is "a"" test

Parameters
k- Parameter name
map- map to add items to (new items will overwrite old items)
template<class T >
void SST::Params::find_set ( const key_type k,
std::set< T > &  set 
) const
inline

Find a Parameter value in the set, and return its value as a set of T's.

The items will be added to the passed in set.

Type T must be either a basic numeric type (including bool), a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion. The values in the set must be enclosed in curly braces ( {} ), and be comma separated (commas in double or single quotes will not be considered a delimiter). If there are no curly braces, the entire string will be considered one value and a single item will be added to the set.

More details about parsing the values out of the string:

Parses a string representing a set of tokens. It is tailored to the types strings you get when passing a python set as the param string. When you call addParam() on a python set in the input file, it will call the str() function on the set, which creates a string with the following format: {item1, item2, item3}

The format of the items depends on where they came from. The string for the items are generated by calling the repr() function on them. For strings, this means they will typically be enclosed in single quotes. It is possible that they end up enclosed in double quotes if the string itself contains a single quote. For strings which contain both single and double quotes, the repr() will create a single quoted string with all internal single quotes escaped with '\'. Most other items used in SST do not enclose the string in quotes, though any string that contains a comma would need to be enclosed in quotes, since the comma is the delimiter character used. This is not done automatically, so if you have something that generates a commma in the string created by repr(), you may need to create an array string manually. Also, any string that starts with a quote character, must end with the same quote character.

Tokens are generated by splitting the string on commas that are not within quotes (double or single). All whitespace at the beginning and end of a token is ignored (unless inside quotes). Once the tokens are generated, any quoted string will have the front and back quotes removed. The '\' for any escaped quote of the same type as the front and back is also removed.

Examples:

These will produce the same results: {1, 2, 3, 4, 5} {'1', '2', '3', '4', '5'}

Examples of strings using double and/or single quotes: 'This is "a" test' -> This is "a" test "This is 'a' test" -> This is 'a' test 'This "is \'a\'" test' -> This "is 'a'" test 'This "is \"a"" test' -> This "is "a"" test

Parameters
k- Parameter name
set- set to add items to (new items will overwrite old items)
Params SST::Params::get_scoped_params ( const std::string &  scope) const

Returns a new parameter object with parameters that match the specified scoped prefix (scopes are separated with "." The keys will be stripped of the "scope." prefix.

Function will search both local and global params, but all params will be copied into the local space of the new Params object.

Parameters
scopeScope to search (anything prefixed with "scope." will be included in the return Params object
Returns
New Params object with the found scoped params.

References enableVerify(), and insert().

std::set< std::string > SST::Params::getKeys ( ) const

Get all the keys contained in the Params object.

This will give both local and global params.

Referenced by empty(), and size().

void SST::Params::insert ( const std::string &  key,
const std::string &  value,
bool  overwrite = true 
)

Add a key/value pair into the param object.

Parameters
keykey to add to the map
valuevalue to add to the map
overwritecontrols whether the key/value pair will overwrite an existing pair in the set

Referenced by SST::ConfigGraph::addStatisticOutputParameter(), and get_scoped_params().

void SST::Params::insert ( const Params params)

Add contents of input Params object to current Params object.

This will also add any pointers to global param sets after the existing pointers to global param sets in this object.

Parameters
paramsParams object that should added to current object
bool SST::Params::is_value_array ( const key_type k) const
inline

Checks to see if the value associated with the given key is considered to be an array.

A value is considered to be an array if it is enclosed in square brackets ([]). No whitespace before or after the brackets is allowed.

Parameters
k- Parameter name
Returns
true if value is an array as described above, false otherwise.
Params & SST::Params::operator= ( const Params old)

Assignment operator.

Parameters
oldParam to be copied

All the elements of old are copied, This will also copy over any references to global param sets

void SST::Params::pushAllowedKeys ( const KeySet_t keys)
Parameters
keysSet of keys to consider valid to add to the stack of legal keys

Referenced by SST::Factory::CreateComponent(), SST::Factory::CreateModule(), SST::Factory::CreateModuleWithComponent(), and SST::Factory::CreateWithParams().

size_t SST::Params::size ( ) const

Returns the size of the Params.

This will count both local and global params.

Returns
number of key/value pairs in this Params object

References getKeys().


The documentation for this class was generated from the following files: